> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abv.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SCIM & Organization API

> Automate user provisioning and project management with organization-scoped API keys and SCIM 2.0

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:

<Steps>
  <Step title="Create organization-scoped API key" icon="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
  </Step>

  <Step title="Authenticate with Basic Auth" icon="lock">
    Organization-scoped API keys use HTTP Basic Authentication:

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

    Example:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Call organization management APIs" icon="arrows-turn-to-dots">
    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.
  </Step>

  <Step title="Integrate with identity providers" icon="diagram-project">
    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.
  </Step>
</Steps>

# Organization Management API

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

## Available Endpoints

<AccordionGroup>
  <Accordion title="Project Management" icon="folder">
    **Create projects**:

    ```bash theme={null}
    POST /api/public/projects
    ```

    **Update project settings**:

    ```bash theme={null}
    PUT /api/public/projects/{projectId}
    ```

    **Delete projects**:

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="API Key Management" icon="key">
    **List project API keys**:

    ```bash theme={null}
    GET /api/public/projects/{projectId}/apiKeys
    ```

    **Create project API key**:

    ```bash theme={null}
    POST /api/public/projects/{projectId}/apiKeys
    ```

    **Delete project API key**:

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="Membership Management" icon="users">
    **Get organization memberships**:

    ```bash theme={null}
    GET /api/public/organizations/memberships
    ```

    **Update organization membership roles**:

    ```bash theme={null}
    PUT /api/public/organizations/memberships
    ```

    **Update project membership roles**:

    ```bash theme={null}
    PUT /api/public/projects/{projectId}/memberships
    ```

    **Remove project membership**:

    ```bash theme={null}
    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
  </Accordion>
</AccordionGroup>

## Example: Programmatically Create a Project

```bash theme={null}
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**:

```json theme={null}
{
  "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

```bash theme={null}
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 →](/developer/platform/administration/role-based-access-controls)

# 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

<AccordionGroup>
  <Accordion title="Service Provider Configuration" icon="gear">
    **Endpoint**: `GET /ServiceProviderConfig`

    Returns 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.
  </Accordion>

  <Accordion title="Resource Types" icon="list">
    **Endpoint**: `GET /ResourceTypes`

    Returns supported SCIM resource types (User, Group, etc.).

    **Use case**: IdP configuration—identity providers determine which resources ABV supports provisioning.
  </Accordion>

  <Accordion title="Schemas" icon="file-lines">
    **Endpoint**: `GET /Schemas`

    Returns SCIM schema definitions for User resources, including supported attributes.

    **Use case**: Attribute mapping—identity providers map their user attributes to ABV's schema.
  </Accordion>

  <Accordion title="User Provisioning" icon="user-plus">
    **List users**:

    ```bash theme={null}
    GET /Users
    ```

    **Create user**:

    ```bash theme={null}
    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**:

    ```bash theme={null}
    GET /Users/{id}
    ```

    **Delete user** (remove from organization):

    ```bash theme={null}
    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.
  </Accordion>
</AccordionGroup>

## SCIM User Lifecycle

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

```mermaid theme={null}
sequenceDiagram
    participant IdP as Identity Provider<br/>(Okta/Azure AD)
    participant SCIM as ABV SCIM API
    participant ABV as ABV Platform
    participant User as User Account

    Note over IdP,ABV: User Created in IdP
    IdP->>SCIM: POST /Users<br/>(user details)
    SCIM->>ABV: Create user account
    ABV->>User: User created with role=NONE
    SCIM-->>IdP: User created response

    Note over IdP,ABV: Role Assignment
    IdP->>SCIM: PUT /Users/{id}<br/>(role attributes)
    SCIM->>ABV: Update org membership
    ABV->>User: Assign role (Member/Admin/etc)
    SCIM-->>IdP: Update confirmed

    Note over IdP,ABV: User Attributes Changed
    IdP->>SCIM: PATCH /Users/{id}<br/>(name, email changes)
    SCIM->>ABV: Update user profile
    ABV->>User: Profile updated
    SCIM-->>IdP: Update confirmed

    Note over IdP,ABV: User Deactivated/Removed
    IdP->>SCIM: DELETE /Users/{id}
    SCIM->>ABV: Remove org membership
    ABV->>User: Revoke access (membership removed)
    SCIM-->>IdP: Deletion confirmed
```

<Steps>
  <Step title="User created in identity provider" icon="user-plus">
    When a new employee is added to your IdP (Okta, Azure AD, Google Workspace) and assigned to the ABV application, the IdP calls:

    ```bash theme={null}
    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`.
  </Step>

  <Step title="Role assignment" icon="user-shield">
    After creation, use membership APIs to assign organizational or project-level roles:

    ```bash theme={null}
    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).
  </Step>

  <Step title="User attributes updated" icon="user-pen">
    When user information changes in the IdP (name, email), the IdP calls:

    ```bash theme={null}
    PATCH /api/public/scim/Users/{id}
    ```

    ABV updates the user's profile accordingly.
  </Step>

  <Step title="User deactivated or removed" icon="user-xmark">
    When an employee leaves or is unassigned from ABV in the IdP, the IdP calls:

    ```bash theme={null}
    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.
  </Step>
</Steps>

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

<Steps>
  <Step title="Create Okta OIDC application" icon="plus">
    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**
  </Step>

  <Step title="Configure application settings" icon="sliders">
    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**.
  </Step>

  <Step title="Contact ABV support for SSO configuration" icon="envelope">
    Email [support@abv.dev](mailto: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.
  </Step>

  <Step title="Test SSO login" icon="arrow-right-to-bracket">
    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 [support@abv.dev](mailto:support@abv.dev) with error messages and Okta application configuration.
  </Step>
</Steps>

## Okta User Provisioning (SCIM)

Automate user lifecycle management by syncing Okta users to ABV.

<Steps>
  <Step title="Create Okta SAML/SCIM application" icon="plus">
    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**
  </Step>

  <Step title="Configure SAML settings" icon="sliders">
    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**.
  </Step>

  <Step title="Enable SCIM provisioning" icon="toggle-on">
    1. In the **General** tab, set **Provisioning** to `SCIM`
    2. Navigate to the **Provisioning** tab
    3. Click **Edit** for the SCIM Connection
  </Step>

  <Step title="Configure SCIM connection" icon="link">
    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**.
  </Step>

  <Step title="Enable provisioning features" icon="check-double">
    In the **Provisioning** tab, under **To App**, enable:

    * **Create Users**
    * **Update User Attributes**
    * **Deactivate Users**

    Click **Save**.
  </Step>

  <Step title="Configure default user roles (optional)" icon="user-shield">
    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.
  </Step>

  <Step title="Assign users to the application" icon="users">
    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.
  </Step>

  <Step title="Verify provisioning" icon="check">
    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).
  </Step>
</Steps>

# Security Best Practices

<AccordionGroup>
  <Accordion title="Protect Organization-Scoped Keys" icon="shield-halved">
    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 code

    [Learn more about audit logs →](/developer/platform/administration/audit-logs)
  </Accordion>

  <Accordion title="Use Least-Privilege Principle" icon="user-lock">
    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.
  </Accordion>

  <Accordion title="Monitor SCIM Provisioning Logs" icon="magnifying-glass-chart">
    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 →](/developer/platform/administration/audit-logs)
  </Accordion>

  <Accordion title="Test in Non-Production First" icon="flask">
    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.
  </Accordion>

  <Accordion title="Implement SSO and SCIM Together" icon="link">
    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.
  </Accordion>
</AccordionGroup>

# Troubleshooting

<AccordionGroup>
  <Accordion title="SCIM Authentication Fails" icon="key">
    **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
  </Accordion>

  <Accordion title="Users Not Provisioning from IdP" icon="user-slash">
    **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)
  </Accordion>

  <Accordion title="SSO Redirect Loop or Errors" icon="arrows-spin">
    **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 [support@abv.dev](mailto: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)
  </Accordion>

  <Accordion title="Organization API Returns 403 Forbidden" icon="lock">
    **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
  </Accordion>
</AccordionGroup>

# Next Steps

<CardGroup cols={2}>
  <Card title="Role-Based Access Controls" icon="user-shield" href="/developer/platform/administration/role-based-access-controls">
    Understand roles and permissions for organization and project access
  </Card>

  <Card title="Audit Logs" icon="file-shield" href="/developer/platform/administration/audit-logs">
    Monitor SCIM provisioning and API usage through audit logs
  </Card>

  <Card title="Public API Reference" icon="code" href="/developer/platform/api-data-platform/public-api">
    Complete API documentation for all organization and project endpoints
  </Card>

  <Card title="Data Deletion" icon="trash" href="/developer/platform/administration/data-deletion">
    Learn about removing users and data for compliance
  </Card>
</CardGroup>