Skip to main content
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

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
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
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

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.
Endpoint: GET /ResourceTypesReturns supported SCIM resource types (User, Group, etc.).Use case: IdP configuration—identity providers determine which resources ABV supports provisioning.
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.
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": "[email protected]",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "emails": [{"value": "[email protected]", "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

  1. Log in to your Okta admin console
  2. Navigate to Applications > Create App Integration
  3. Choose OIDC - OpenID Connect as the sign-in method and click Next
  4. 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 [email protected] 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:
  1. Assign users to your Okta ABV application
  2. Navigate to ABV’s login page
  3. Enter your email address
  4. You’ll be automatically redirected to Okta for authentication
  5. After successful Okta login, you’re redirected back to ABV logged in
Troubleshooting: If SSO doesn’t work, contact [email protected] 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

  1. Log in to your Okta admin console
  2. Navigate to Applications > Create App Integration
  3. 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

  1. In the General tab, set Provisioning to SCIM
  2. Navigate to the Provisioning tab
  3. 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:
  1. Navigate to Organization Settings > API Keys in ABV
  2. Click Create new organization API key
  3. 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:
  1. Navigate to Provisioning tab > Profile Editor
  2. 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
  3. Click Save
  4. 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

  1. Navigate to the Assignments tab
  2. Click Assign > Assign to People
  3. Select users to provision to ABV
  4. Optionally override roles per user (if role attribute is configured)
  5. Click Done and then Save
Users should now appear in your ABV organization with configured roles.

Verify provisioning

  1. In ABV, navigate to Organization Settings > Members
  2. Confirm Okta-provisioned users appear with correct roles
  3. 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

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 →
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.
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 →
Before configuring production SCIM provisioning:
  1. Create a test ABV organization
  2. Configure SCIM provisioning to the test organization
  3. Provision test users and verify role mappings work correctly
  4. Test deprovisioning (user removal)
  5. Verify audit logs capture all operations
  6. Only then configure production provisioning
Why: SCIM misconfigurations can create hundreds of users with incorrect roles. Test thoroughly before production.
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

Symptoms: IdP reports authentication errors when testing SCIM credentials.Possible causes:
  1. Incorrect API keys: Wrong public or secret key
  2. Wrong key type: Using project-scoped key instead of organization-scoped key
  3. Revoked keys: Keys were deleted or expired
  4. 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
Symptoms: Assigned users in IdP don’t appear in ABV organization.Possible causes:
  1. Provisioning not enabled: IdP provisioning features not activated
  2. Attribute mapping errors: Required fields missing or incorrectly mapped
  3. SCIM connectivity issues: IdP can’t reach ABV’s SCIM endpoints
  4. 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)
Symptoms: Users get stuck in redirect loop or see SSO error page.Possible causes:
  1. Incorrect redirect URIs: Mismatch between IdP configuration and ABV’s callback URL
  2. SSO not configured in ABV: Support hasn’t enabled SSO for your organization yet
  3. Client ID/Secret mismatch: IdP application credentials don’t match ABV configuration
  4. Domain mismatch: Using wrong ABV region (US vs EU)
Resolution:
  • Verify redirect URIs match exactly (including https://)
  • Confirm ABV support has configured SSO (contact [email protected])
  • 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)
Symptoms: API calls with organization key return 403 or permission errors.Possible causes:
  1. Wrong key scope: Using project-scoped key for organization endpoints
  2. Insufficient permissions: Organization key belongs to user without required role
  3. 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