Skip to content

Bruno SCIM API

The Bruno SCIM API provides a direct way to manage users programmatically without requiring integration through identity provider applications like Okta or Microsoft Entra. This is ideal for organizations that want to build custom integrations.

Prerequisites: Before using the Bruno SCIM API, you must first enable SCIM provisioning in Bruno and generate an API key. Follow the Enabling SCIM Provisioning section in the overview page to complete this setup and save your API key for use in the steps below.

Who Should Use the SCIM API?

The Bruno SCIM API is designed for:

  • Organizations with custom identity providers that do not want to leverage a SCIM 2.0 configuration
  • Development teams building custom user management workflows
  • System administrators who need programmatic control over user provisioning

API Collection

Bruno provides a complete API collection to help you get started quickly:

📁 Bruno SCIM API Collection

<img src="https://fetch.usebruno.com/button.svg" alt="Fetch in Bruno" style={{width: '130px', height: '30px'}} width="128" height="32" />

This collection includes: - User management endpoints (create, read, update, delete) - Service provider configuration endpoints - Pre-configured environments for testing - Example requests and responses for all operations

Authentication

All SCIM API requests require authentication using a bearer token:

Authorization: Bearer YOUR_SCIM_API_TOKEN

The bearer token is specific to your Bruno authentication domain and can be generated from the SCIM Provisioning settings in your license portal.

Supported SCIM Operations

Bruno's SCIM implementation follows the SCIM 2.0 specification and supports the following operations:

User Operations

Operation HTTP Method Endpoint Description
Create User POST /Users Provision a new user with Bruno license
Get User GET /Users/{id} Retrieve user information by ID
Update User PUT /Users/{id} Update user attributes
Patch User PATCH /Users/{id} Partial user updates
Delete User DELETE /Users/{id} Deprovision user and revoke license
List Users GET /Users Retrieve all users with pagination
Filter Users GET /Users?filter=... Search users by attributes

User Schema

Bruno supports the following SCIM user attributes:

Required Fields

  • userName - User's email address (unique identifier)
  • emails - Array of email addresses (primary email required)
  • active - Boolean indicating if user should have access

Optional Fields

  • externalId - External system identifier for the user
  • name.givenName - First name
  • name.familyName - Last name
  • timezone - User's timezone (IANA format, e.g., "America/Los_Angeles")
  • roles - Array of role values. Used to provision License Manager administrators; see Provisioning administrators

Example API Calls

Create a User

POST /Users
Authorization: Bearer YOUR_TOKEN

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "externalId": "emp-12345",
  "userName": "john.doe@company.com",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "emails": [{
    "value": "john.doe@company.com",
    "primary": true
  }],
  "timezone": "America/New_York",
  "active": true
}

List Users

Retrieve the users in your subscription. Results are returned in pages, ordered by creation date (oldest first).

GET /Users?startIndex=1&count=100
Authorization: Bearer YOUR_TOKEN

Query parameters

Parameter Default Description
startIndex 1 1-based index of the first result to return
count 100 Number of results per page (maximum 200)
filter - SCIM filter expression. See Filter Users
attributes - Comma-separated list of attributes to include in each user
excludedAttributes - Comma-separated list of attributes to leave out of each user

By default, only active users are returned. To include deactivated users, add a filter on active, for example filter=active eq true or active eq false.

Example response

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 2,
  "itemsPerPage": 2,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "673f2fc148b546efd5bbbbce",
      "externalId": "emp-12345",
      "userName": "john.doe@company.com",
      "name": {
        "formatted": "John Doe",
        "givenName": "John",
        "familyName": "Doe"
      },
      "displayName": "John Doe",
      "active": true,
      "emails": [{ "value": "john.doe@company.com", "type": "work", "primary": true }],
      "meta": {
        "resourceType": "User",
        "created": "2025-01-07T07:46:38.482Z",
        "lastModified": "2026-10-13T14:36:16.673Z",
        "lastSeenAt": "2026-10-13T14:36:16.673Z",
        "location": "https://license.usebruno.com/scim/v2/Users/673f2fc148b546efd5bbbbce"
      }
    },
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "68e79210a79a31703985d98b",
      "userName": "jane.smith@company.com",
      "name": {
        "formatted": "Jane Smith",
        "givenName": "Jane",
        "familyName": "Smith"
      },
      "displayName": "Jane Smith",
      "active": true,
      "emails": [{ "value": "jane.smith@company.com", "type": "work", "primary": true }],
      "meta": {
        "resourceType": "User",
        "created": "2026-09-07T14:11:40.608Z",
        "lastModified": "2026-09-07T14:11:40.608Z",
        "lastSeenAt": null,
        "location": "https://license.usebruno.com/scim/v2/Users/68e79210a79a31703985d98b"
      }
    }
  ]
}

To page through all users, increase startIndex by count on each request until you have retrieved totalResults users.

User fields

Field Description
meta.created When the user was first provisioned in Bruno. Reactivating a deactivated user keeps the original date
meta.lastModified When the user record last changed. SCIM updates, deactivation, and reactivation all update it, as can other account events in Bruno. It may be later than your most recent SCIM request
meta.lastSeenAt Bruno-specific. The timestamp of the user's most recent license check-in, or null if none has been recorded
meta.location The full URL of this user resource. Use it for GET, PUT, PATCH, and DELETE requests on the user

Filter Users

Use the filter parameter to search users. Bruno supports the SCIM operators eq, ne, co, sw, ew, pr, gt, ge, lt, and le, combined with and, or, and not.

Filterable attributes: userName, emails.value, id, externalId, active, displayName, meta.created, meta.lastModified, and meta.lastSeenAt.

# Find a user by email
GET /Users?filter=userName eq "john.doe@company.com"

URL-encode the filter value when sending it from code or the command line.

Error Handling

The Bruno SCIM API returns standard HTTP status codes and SCIM-compliant error responses:

  • 200 OK - Successful operation
  • 201 Created - Resource created successfully
  • 204 No Content - Successful operation with no response body
  • 400 Bad Request - Invalid request format or missing required fields
  • 401 Unauthorized - Invalid or missing authentication token
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource already exists or conflict with current state
  • 500 Internal Server Error - Server error

Rate Limiting

The Bruno SCIM API implements rate limiting to ensure service stability:

  • Rate limit: 100 requests per minute per authentication domain
  • Burst limit: 20 requests per 10-second window
  • Headers: Rate limit information is included in response headers

Best Practices

Security

  • Secure token storage: Store API tokens securely and rotate them regularly
  • HTTPS only: Always use HTTPS for API requests
  • Minimal permissions: Use dedicated service accounts with minimal required permissions

Performance

  • Batch operations: Use PATCH operations for bulk updates when possible
  • Pagination: Implement proper pagination for large result sets
  • Caching: Cache user data to reduce API calls

Error Handling

  • Retry logic: Implement exponential backoff for transient errors
  • Logging: Log all API interactions for debugging and audit purposes
  • Validation: Validate data before sending API requests

Getting Started

  1. Download the collection: Clone or download the Bruno SCIM API Collection
  2. Configure environment: Set up your base URL and API token in the environment variables
  3. Test connectivity: Start with the Service Provider Config endpoint to verify your setup
  4. Create test user: Use the Create User endpoint to provision your first user
  5. Explore operations: Try different SCIM operations using the provided examples

Next Steps