Enterprise organizations need programmatic control over users, projects, and access permissions. Manually onboarding employees through the UI, creating projects for each new team, and managing role assignments across hundreds of users doesn’t scale.

How Organization-Scoped APIs Work

Organization-scoped API keys and SCIM endpoints enable enterprise-grade automation:

Create organization-scoped API key

Organization-scoped API keys have elevated permissions compared to project-scoped keys. They can manage projects, users, and memberships across the entire organization.Create organization keys in Organization Settings > API Keys or programmatically via the Organization Management API (if you already have an organization key).Permissions: Create/modify/delete projects, manage organization and project memberships, create API keys for projects

Authenticate with Basic Auth

Organization-scoped API keys use HTTP Basic Authentication:

Username: Public key (starts with pk-org-...)
Password: Secret key (starts with sk-org-...)

Example:

curl -u pk-org-xxx:sk-org-yyy https://app.abv.dev/api/public/projects

Security: Treat organization keys like root credentials. Restrict access, rotate regularly, and never commit to version control.

Call organization management APIs

Use organization-scoped keys to call administrative endpoints:

Projects: Create, update, delete projects programmatically
API Keys: Generate project-scoped API keys for applications
Memberships: Assign users to organizations and projects with specific roles
SCIM endpoints: Automate user lifecycle management

All endpoints return standard JSON responses and use RESTful conventions.

Integrate with identity providers

For SCIM provisioning:

Configure your IdP (Okta, Azure AD, Google Workspace) to use ABV’s SCIM endpoints
Provide organization-scoped credentials for authentication
Map IdP user attributes to ABV roles
Enable automatic provisioning and deprovisioning

Users created in your IdP automatically appear in ABV with configured roles.

Organization Management API

Organization-scoped API keys enable programmatic administration of ABV projects and memberships.

Available Endpoints

Project Management

Create projects:

POST /api/public/projects

Update project settings:

PUT /api/public/projects/{projectId}

Delete projects:

DELETE /api/public/projects/{projectId}

Use cases:

Infrastructure-as-code: Provision projects for new teams or environments
Multi-tenant deployments: Create customer-specific projects programmatically
Environment management: Automate creation of staging/production projects

API Key Management

List project API keys:

GET /api/public/projects/{projectId}/apiKeys

Create project API key:

POST /api/public/projects/{projectId}/apiKeys

Delete project API key:

DELETE /api/public/projects/{projectId}/apiKeys/{apiKeyId}

Use cases:

CI/CD automation: Generate API keys for deployment pipelines
Key rotation: Programmatically rotate project keys on schedule
Customer onboarding: Create API keys for new multi-tenant customers

Membership Management

Get organization memberships:

GET /api/public/organizations/memberships

Update organization membership roles:

PUT /api/public/organizations/memberships

Update project membership roles:

PUT /api/public/projects/{projectId}/memberships

Remove project membership:

DELETE /api/public/projects/{projectId}/memberships

Use cases:

Bulk role assignments: Update roles for multiple users at once
Team reorganizations: Reassign project memberships when teams change
Access audits: Programmatically review and adjust access levels

Example: Programmatically Create a Project

curl -X POST https://app.abv.dev/api/public/projects \
  -u pk-org-xxx:sk-org-yyy \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production - Customer Analytics",
    "description": "Production project for customer analytics features"
  }'

Response:

{
  "id": "proj-abc123",
  "name": "Production - Customer Analytics",
  "description": "Production project for customer analytics features",
  "createdAt": "2025-01-15T10:30:00Z"
}

Example: Assign User to Project with Role

curl -X PUT https://app.abv.dev/api/public/projects/proj-abc123/memberships \
  -u pk-org-xxx:sk-org-yyy \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-456",
    "role": "ADMIN"
  }'

Available roles: OWNER, ADMIN, MEMBER, VIEWER, NONE Learn more about roles →

SCIM 2.0 User Provisioning

ABV implements SCIM 2.0 (System for Cross-domain Identity Management) for automated user lifecycle management.

SCIM Base URL

All SCIM endpoints use this base URL:

https://app.abv.dev/api/public/scim

Authentication

SCIM endpoints use HTTP Basic Authentication with organization-scoped API keys:

Username: Organization public key (pk-org-...)
Password: Organization secret key (sk-org-...)

SCIM Endpoints

Service Provider Configuration

Endpoint: GET /ServiceProviderConfigReturns SCIM service capabilities and configuration (supported operations, authentication schemes, bulk operations support).Use case: IdP autodiscovery—identity providers query this endpoint to determine ABV’s SCIM capabilities.

Resource Types

Endpoint: GET /ResourceTypesReturns supported SCIM resource types (User, Group, etc.).Use case: IdP configuration—identity providers determine which resources ABV supports provisioning.

Schemas

Endpoint: GET /SchemasReturns SCIM schema definitions for User resources, including supported attributes.Use case: Attribute mapping—identity providers map their user attributes to ABV’s schema.

User Provisioning

List users:

GET /Users

Create user:

POST /Users

Creates a new user if email doesn’t exist, then adds the user to the organization with role NONE by default.Get user:

GET /Users/{id}

Delete user (remove from organization):

DELETE /Users/{id}

Important: DELETE removes the user’s membership from the organization but does not delete the user account itself. The user remains in ABV and can be added to other organizations.Use case: Automated employee onboarding/offboarding synchronized with your identity provider.

SCIM User Lifecycle

The following diagram shows how user provisioning flows from your identity provider to ABV:

User created in identity provider

When a new employee is added to your IdP (Okta, Azure AD, Google Workspace) and assigned to the ABV application, the IdP calls:

POST /api/public/scim/Users
{
  "userName": "employee@company.com",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "emails": [{"value": "employee@company.com", "primary": true}],
  "active": true
}

ABV creates the user if they don’t exist and adds them to the organization with role NONE.

Role assignment

After creation, use membership APIs to assign organizational or project-level roles:

PUT /api/public/organizations/memberships
{
  "userId": "user-123",
  "role": "MEMBER"
}

Alternatively, configure roles in your IdP’s attribute mapping (see Okta setup guide below for role mapping configuration).

User attributes updated

When user information changes in the IdP (name, email), the IdP calls:

PATCH /api/public/scim/Users/{id}

ABV updates the user’s profile accordingly.

User deactivated or removed

When an employee leaves or is unassigned from ABV in the IdP, the IdP calls:

DELETE /api/public/scim/Users/{id}

ABV removes the user’s organization membership, revoking their access immediately. The user account persists in ABV for audit trails.

Okta Integration Guide

Okta is a popular enterprise identity provider. This guide covers setting up both authentication (SSO) and user provisioning (SCIM).

Okta Authentication (SSO via OIDC)

ABV supports OpenID Connect (OIDC) for Single Sign-On through Okta.

Create Okta OIDC application

Log in to your Okta admin console
Navigate to Applications > Create App Integration
Choose OIDC - OpenID Connect as the sign-in method and click Next
Choose Web Application as the application type and click Next

Configure application settings

Fill in the application settings using your ABV domain:

App name: ABV
Login redirect URIs: https://your-abv-domain.dev/api/auth/callback/okta
- US region: https://app.abv.dev/api/auth/callback/okta
- EU region: https://eu.app.abv.dev/api/auth/callback/okta
Logout redirect URIs: https://your-abv-domain.dev/
- US region: https://app.abv.dev/
- EU region: https://eu.app.abv.dev/

Click Save.

Contact ABV support for SSO configuration

Email support@abv.dev with:

Okta application Client ID
Okta application Client Secret
Your Okta domain (e.g., company.okta.com)

ABV support will configure SSO for your organization.

Test SSO login

Once configured:

Assign users to your Okta ABV application
Navigate to ABV’s login page
Enter your email address
You’ll be automatically redirected to Okta for authentication
After successful Okta login, you’re redirected back to ABV logged in

Troubleshooting: If SSO doesn’t work, contact support@abv.dev with error messages and Okta application configuration.

Okta User Provisioning (SCIM)

Automate user lifecycle management by syncing Okta users to ABV.

Create Okta SAML/SCIM application

Log in to your Okta admin console
Navigate to Applications > Create App Integration
Choose SAML 2.0 as the sign-in method and click Next

Configure SAML settings

Fill in the application settings:

App name: ABV SCIM
Single sign-on URL: https://your-abv-domain.dev/api/auth/callback/okta
Audience URI: abv

Click Next and then Finish.

Enable SCIM provisioning

In the General tab, set Provisioning to SCIM
Navigate to the Provisioning tab
Click Edit for the SCIM Connection

Configure SCIM connection

Enter your SCIM connection details:

SCIM connector base URL: https://your-abv-domain.dev/api/public/scim
- US region: https://app.abv.dev/api/public/scim
- EU region: https://eu.app.abv.dev/api/public/scim
Unique identifier field for users: userName
Supported provisioning actions: Check all three:
- Import new Users and Profile Updates
- Push New Users
- Push Profile Updates
Basic Auth - Username: Organization public key from ABV (starts with pk-org-...)
Basic Auth - Password: Organization secret key from ABV (starts with sk-org-...)

How to get organization API keys:

Navigate to Organization Settings > API Keys in ABV
Click Create new organization API key
Copy the public and secret keys

Click Test API Credentials to verify connectivity, then Save.

Enable provisioning features

In the Provisioning tab, under To App, enable:

Create Users
Update User Attributes
Deactivate Users

Click Save.

Configure default user roles (optional)

To automatically assign roles to provisioned users:

Navigate to Provisioning tab > Profile Editor
Click Add Attribute:
- Data type: string array
- Display Name: ABV Roles
- Variable Name: roles
- External Name: roles
- External Namespace: urn:ietf:params:scim:schemas:core:2.0:User
- Attribute members: NONE, VIEWER, MEMBER, ADMIN
- Attribute type: Personal
Click Save
In Provisioning tab > Attribute Mappings, set the default value for roles attribute to your desired default (e.g., MEMBER)

Use case: All users provisioned from Okta automatically receive the MEMBER role without manual assignment.

Assign users to the application

Navigate to the Assignments tab
Click Assign > Assign to People
Select users to provision to ABV
Optionally override roles per user (if role attribute is configured)
Click Done and then Save

Users should now appear in your ABV organization with configured roles.

Verify provisioning

In ABV, navigate to Organization Settings > Members
Confirm Okta-provisioned users appear with correct roles
Test login with a provisioned user (they should SSO through Okta if both SSO and SCIM are configured)

Troubleshooting: If users don’t appear, check Okta’s provisioning logs (Applications > ABV SCIM > Provisioning > Integration > View Logs).

Security Best Practices

Protect Organization-Scoped Keys

Organization keys have elevated privileges across all projects and users. Treat them like root credentials:

Storage: Use secrets management systems (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault)
Access control: Limit who can create or view organization keys (Owners only)
Rotation: Rotate organization keys quarterly or after suspected compromise
Audit: Monitor usage of organization keys through audit logs

Never: Commit keys to version control, share via email/Slack, or embed in application codeLearn more about audit logs →

Use Least-Privilege Principle

Not every automation needs organization-scoped keys. Use project-scoped keys when possible:

Application tracing: Project-scoped key (write traces to one project)
Customer API key generation: Organization-scoped key (create keys across projects)
User provisioning: Organization-scoped key (SCIM requires org-level access)
Project management: Organization-scoped key (create/delete projects)

Pattern: Use organization keys only for truly cross-project administrative tasks.

Monitor SCIM Provisioning Logs

Regularly review SCIM provisioning logs in both ABV and your identity provider:

ABV audit logs: Track user creation, role changes, and membership modifications
IdP provisioning logs: Verify successful synchronization and catch errors
Anomaly detection: Unexpected user creations, bulk role changes, or provisioning failures

Alert on: Failed SCIM operations (authentication errors, attribute mapping failures, quota exceeded).Learn more about audit logs →

Test in Non-Production First

Before configuring production SCIM provisioning:

Create a test ABV organization
Configure SCIM provisioning to the test organization
Provision test users and verify role mappings work correctly
Test deprovisioning (user removal)
Verify audit logs capture all operations
Only then configure production provisioning

Why: SCIM misconfigurations can create hundreds of users with incorrect roles. Test thoroughly before production.

Implement SSO and SCIM Together

For maximum security and operational efficiency, implement both SSO and SCIM:SSO benefits:

Centralized authentication
Enforce MFA policies
Immediate login revocation on offboarding

SCIM benefits:

Automated user lifecycle
Consistent role assignments
No manual user management

Together: Employees are automatically provisioned with correct roles and authenticate via your existing identity provider—completely hands-off user management.

Troubleshooting

SCIM Authentication Fails

Symptoms: IdP reports authentication errors when testing SCIM credentials.Possible causes:

Incorrect API keys: Wrong public or secret key
Wrong key type: Using project-scoped key instead of organization-scoped key
Revoked keys: Keys were deleted or expired
Incorrect base URL: Typo in SCIM connector base URL

Resolution:

Verify you’re using organization-scoped keys (pk-org-... and sk-org-...)
Confirm keys are active in Organization Settings > API Keys
Check SCIM base URL matches ABV region (US: app.abv.dev, EU: eu.app.abv.dev)
Regenerate organization keys if uncertain about validity

Users Not Provisioning from IdP

Symptoms: Assigned users in IdP don’t appear in ABV organization.Possible causes:

Provisioning not enabled: IdP provisioning features not activated
Attribute mapping errors: Required fields missing or incorrectly mapped
SCIM connectivity issues: IdP can’t reach ABV’s SCIM endpoints
Role mapping misconfiguration: Users created but with NONE role (invisible in some views)

Resolution:

Check IdP provisioning logs for specific error messages
Verify “Create Users” is enabled in IdP provisioning settings
Test SCIM connectivity with curl using organization credentials
Check ABV Organization Settings > Members for users with NONE role
Review attribute mappings (email/userName are required)

SSO Redirect Loop or Errors

Symptoms: Users get stuck in redirect loop or see SSO error page.Possible causes:

Incorrect redirect URIs: Mismatch between IdP configuration and ABV’s callback URL
SSO not configured in ABV: Support hasn’t enabled SSO for your organization yet
Client ID/Secret mismatch: IdP application credentials don’t match ABV configuration
Domain mismatch: Using wrong ABV region (US vs EU)

Resolution:

Verify redirect URIs match exactly (including https://)
Confirm ABV support has configured SSO (contact support@abv.dev)
Double-check Client ID and Secret were provided to ABV support correctly
Ensure users access the correct ABV region (app.abv.dev or eu.app.abv.dev)

Organization API Returns 403 Forbidden

Symptoms: API calls with organization key return 403 or permission errors.Possible causes:

Wrong key scope: Using project-scoped key for organization endpoints
Insufficient permissions: Organization key belongs to user without required role
Endpoint requires organization key: Endpoint explicitly requires organization scope

Resolution:

Verify you’re using organization-scoped key (pk-org-...)
Check that the user who created the organization key has Owner or Admin role
Review API documentation for endpoint’s required permissions

Next Steps

Role-Based Access Controls

Understand roles and permissions for organization and project access

Audit Logs

Monitor SCIM provisioning and API usage through audit logs

Public API Reference

Complete API documentation for all organization and project endpoints

Data Deletion

Learn about removing users and data for compliance

Documentation Index

​How Organization-Scoped APIs Work

​Organization Management API

​Available Endpoints

​Example: Programmatically Create a Project

​Example: Assign User to Project with Role

​SCIM 2.0 User Provisioning

​SCIM Base URL

​Authentication

​SCIM Endpoints

​SCIM User Lifecycle

​Okta Integration Guide

​Okta Authentication (SSO via OIDC)

​Okta User Provisioning (SCIM)

​Security Best Practices

​Troubleshooting

​Next Steps

Role-Based Access Controls

Audit Logs

Public API Reference

Data Deletion

How Organization-Scoped APIs Work

Organization Management API

Available Endpoints

Example: Programmatically Create a Project

Example: Assign User to Project with Role

SCIM 2.0 User Provisioning

SCIM Base URL

Authentication

SCIM Endpoints

SCIM User Lifecycle

Okta Integration Guide

Okta Authentication (SSO via OIDC)

Okta User Provisioning (SCIM)

Security Best Practices

Troubleshooting

Next Steps