openapi: 3.2.0 info: title: Routebase Public SCIM API description: 'This reference covers the part of the Routebase API that is a commitment to customers.' version: 1.0.0 servers: - url: https://api.routebase.dev tags: - name: SCIM description: 'SCIM 2.0 user and group provisioning, as consumed by Okta, Microsoft Entra ID and other identity providers. Available on plans that include SSO.' paths: /scim/v2/{orgSlug}/Groups: get: tags: - SCIM summary: List groups description: 'Returns the provisioned groups of an organization in a SCIM ListResponse envelope. Groups map onto Routebase teams, and a group mapping decides which role its members receive.' operationId: scimListGroups parameters: - $ref: '#/components/parameters/ScimCount' - name: filter in: query description: SCIM filter expression, for example `displayName eq "Engineering"`. schema: type: string - $ref: '#/components/parameters/OrgSlug' - $ref: '#/components/parameters/ScimStartIndex' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us responses: '200': description: A SCIM ListResponse of groups. content: application/scim+json: schema: $ref: '#/components/schemas/ScimGroupListResponse' '400': $ref: '#/components/responses/ScimError' '404': $ref: '#/components/responses/ScimError' '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM post: tags: - SCIM summary: Provision a group description: Creates a group and adds the members you send with it. operationId: scimCreateGroup parameters: - $ref: '#/components/parameters/OrgSlug' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us requestBody: content: application/scim+json: schema: $ref: '#/components/schemas/ScimGroupResource' required: true responses: '201': description: The group was provisioned. content: application/scim+json: schema: $ref: '#/components/schemas/ScimGroupResource' '400': $ref: '#/components/responses/ScimError' '409': $ref: '#/components/responses/ScimError' '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM /scim/v2/{orgSlug}/Groups/{id}: get: tags: - SCIM summary: Get a group description: Returns one provisioned group with its members. operationId: scimGetGroup parameters: - $ref: '#/components/parameters/ScimId' - $ref: '#/components/parameters/OrgSlug' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us responses: '200': description: The group. content: application/scim+json: schema: $ref: '#/components/schemas/ScimGroupResource' '404': $ref: '#/components/responses/ScimError' '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM patch: tags: - SCIM summary: Patch a group description: 'Applies a SCIM PatchOp to a group, which is how an identity provider adds and removes members as people join and leave a team.' operationId: scimPatchGroup parameters: - $ref: '#/components/parameters/ScimId' - $ref: '#/components/parameters/OrgSlug' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us requestBody: content: application/scim+json: schema: $ref: '#/components/schemas/ScimPatchRequest' required: true responses: '200': description: The patched group. content: application/scim+json: schema: $ref: '#/components/schemas/ScimGroupResource' '400': $ref: '#/components/responses/ScimError' '404': $ref: '#/components/responses/ScimError' '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM delete: tags: - SCIM summary: Deprovision a group description: Removes a group. Its members keep their organization membership. operationId: scimDeleteGroup parameters: - $ref: '#/components/parameters/ScimId' - $ref: '#/components/parameters/OrgSlug' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us responses: '204': description: The group was removed. '404': $ref: '#/components/responses/ScimError' '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM /scim/v2/{orgSlug}/ResourceTypes: get: tags: - SCIM summary: List the supported resource types description: Returns the SCIM resource types this service exposes, which are User and Group. operationId: scimResourceTypes parameters: - $ref: '#/components/parameters/OrgSlug' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us responses: '200': description: The resource types. content: application/scim+json: schema: type: object '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM /scim/v2/{orgSlug}/Schemas: get: tags: - SCIM summary: List the supported schemas description: Returns the SCIM schemas backing the User and Group resources. operationId: scimSchemas parameters: - $ref: '#/components/parameters/OrgSlug' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us responses: '200': description: The schemas. content: application/scim+json: schema: type: object '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM /scim/v2/{orgSlug}/ServiceProviderConfig: get: tags: - SCIM summary: Describe what this SCIM service supports description: 'Returns the SCIM service provider configuration, which identity providers read during setup to learn which operations are available.' operationId: scimServiceProviderConfig parameters: - $ref: '#/components/parameters/OrgSlug' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us responses: '200': description: The service provider configuration. content: application/scim+json: schema: type: object '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM /scim/v2/{orgSlug}/Users: get: tags: - SCIM summary: List users description: 'Returns the provisioned users of an organization in a SCIM ListResponse envelope. Identity providers use the `filter` parameter to look a user up by `userName` before deciding whether to create or update.' operationId: scimListUsers parameters: - $ref: '#/components/parameters/ScimCount' - name: filter in: query description: SCIM filter expression, for example `userName eq "ada@example.com"`. schema: type: string - $ref: '#/components/parameters/OrgSlug' - $ref: '#/components/parameters/ScimStartIndex' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us responses: '200': description: A SCIM ListResponse of users. content: application/scim+json: schema: $ref: '#/components/schemas/ScimUserListResponse' '400': $ref: '#/components/responses/ScimError' '404': $ref: '#/components/responses/ScimError' '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM post: tags: - SCIM summary: Provision a user description: 'Creates a user in the organization. A user provisioned this way joins with the default member role, and further role changes stay with Routebase rather than the identity provider.' operationId: scimCreateUser parameters: - $ref: '#/components/parameters/OrgSlug' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us requestBody: content: application/scim+json: schema: $ref: '#/components/schemas/ScimUserResource' required: true responses: '201': description: The user was provisioned. content: application/scim+json: schema: $ref: '#/components/schemas/ScimUserResource' '400': $ref: '#/components/responses/ScimError' '409': $ref: '#/components/responses/ScimError' '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM /scim/v2/{orgSlug}/Users/{id}: get: tags: - SCIM summary: Get a user description: Returns one provisioned user. operationId: scimGetUser parameters: - $ref: '#/components/parameters/ScimId' - $ref: '#/components/parameters/OrgSlug' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us responses: '200': description: The user. content: application/scim+json: schema: $ref: '#/components/schemas/ScimUserResource' '404': $ref: '#/components/responses/ScimError' '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM put: tags: - SCIM summary: Replace a user description: 'Replaces the attributes of a user wholesale. Attributes you leave out are cleared, so send the complete resource rather than a partial one.' operationId: scimReplaceUser parameters: - $ref: '#/components/parameters/ScimId' - $ref: '#/components/parameters/OrgSlug' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us requestBody: content: application/scim+json: schema: $ref: '#/components/schemas/ScimUserResource' required: true responses: '200': description: The updated user. content: application/scim+json: schema: $ref: '#/components/schemas/ScimUserResource' '400': $ref: '#/components/responses/ScimError' '404': $ref: '#/components/responses/ScimError' '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM patch: tags: - SCIM summary: Patch a user description: 'Applies a SCIM PatchOp to a user. This is the call an identity provider makes to deactivate someone, by setting `active` to false, which is a soft removal that keeps the audit trail intact.' operationId: scimPatchUser parameters: - $ref: '#/components/parameters/ScimId' - $ref: '#/components/parameters/OrgSlug' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us requestBody: content: application/scim+json: schema: $ref: '#/components/schemas/ScimPatchRequest' required: true responses: '200': description: The patched user. content: application/scim+json: schema: $ref: '#/components/schemas/ScimUserResource' '400': $ref: '#/components/responses/ScimError' '404': $ref: '#/components/responses/ScimError' '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM delete: tags: - SCIM summary: Deprovision a user description: Removes a user from the organization. operationId: scimDeleteUser parameters: - $ref: '#/components/parameters/ScimId' - $ref: '#/components/parameters/OrgSlug' - name: X-RB-Region in: header description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401. schema: type: string example: us responses: '204': description: The user was removed. '404': $ref: '#/components/responses/ScimError' '429': description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait. SCIM is counted per source IP. headers: Retry-After: description: Seconds to wait before retrying. required: true schema: type: integer format: int32 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - ScimBearerAuth: [] x-routebase-folder-path: SCIM components: schemas: Problem: required: - status type: object properties: type: type: string description: A URI identifying the problem type. title: type: string description: A short summary of the problem type. status: type: integer description: The HTTP status code. format: int32 detail: type: string description: A human readable explanation. instance: type: string description: The path that produced the error. code: type: string description: 'The stable machine readable error code, for example `CONCURRENCY_CONFLICT`, `PROJECT_LOCKED`, `API_KEY_SCOPE_DENIED` or `NOT_A_MEMBER`. ' description: 'The error shape of the API, which follows RFC 9457. Branch on `code`, because `detail` is written for people and may be reworded. ' ScimGroupMemberRef: required: - value type: object properties: value: type: string description: SCIM id of the member. display: type: - 'null' - string description: Display name of the member, for readability. $ref: type: - 'null' - string description: URL of the member resource. type: type: - 'null' - string description: Kind of member. Routebase only supports User. default: User description: A reference from a group to one of its members. ScimUserResource: required: - schemas - id - userName - emails - active - meta type: object properties: schemas: type: array items: type: string description: Always contains `urn:ietf:params:scim:schemas:core:2.0:User`. id: type: string description: SCIM id of the user. externalId: type: - 'null' - string description: The identifier the identity provider uses. userName: type: string description: The login name, which is the email address. name: oneOf: - $ref: '#/components/schemas/ScimName' - type: 'null' description: Structured name parts. Identity providers usually send given and family name. emails: type: array items: $ref: '#/components/schemas/ScimEmail' description: Email addresses of the user. Exactly one carries primary. active: type: boolean description: Setting this to false deactivates the user without deleting the record. meta: description: Resource metadata written by Routebase, not by the identity provider. $ref: '#/components/schemas/ScimMeta' description: A SCIM 2.0 user, as identity providers create and update it. ScimMeta: required: - resourceType - created - lastModified - location type: object properties: resourceType: type: string description: Either `User` or `Group`. created: type: string description: When Routebase created the resource, in UTC. format: date-time lastModified: type: string description: When the resource last changed, in UTC. format: date-time location: type: string description: URL of this resource. version: type: - 'null' - string description: Entity tag of the resource, when the provider asked for one. description: SCIM resource metadata, written by Routebase rather than by the identity provider. ScimGroupListResponse: required: - schemas - totalResults - startIndex - itemsPerPage - Resources type: object properties: schemas: type: array items: type: string description: Always contains `urn:ietf:params:scim:api:messages:2.0:ListResponse`. totalResults: type: integer description: Total number of matching groups, ignoring paging. format: int32 startIndex: type: integer description: 1-based index of the first entry in this page. format: int32 itemsPerPage: type: integer description: How many entries this page holds. format: int32 Resources: type: array items: $ref: '#/components/schemas/ScimGroupResource' description: The groups on this page. Capitalised because SCIM defines it that way. description: A SCIM ListResponse envelope holding groups. ScimError: required: - schemas - detail - status type: object properties: schemas: type: array items: type: string description: Always contains `urn:ietf:params:scim:api:messages:2.0:Error`. detail: type: string description: What went wrong, written for a person reading a provisioning log. status: type: string description: The HTTP status code, as a string. scimType: type: - 'null' - string description: The SCIM error type, for example `invalidFilter`. description: The SCIM error envelope. It replaces the problem+json shape on every SCIM endpoint. ScimUserListResponse: required: - schemas - totalResults - startIndex - itemsPerPage - Resources type: object properties: schemas: type: array items: type: string description: Always contains `urn:ietf:params:scim:api:messages:2.0:ListResponse`. totalResults: type: integer description: Total number of matching users, ignoring paging. format: int32 startIndex: type: integer description: 1-based index of the first entry in this page. format: int32 itemsPerPage: type: integer description: How many entries this page holds. format: int32 Resources: type: array items: $ref: '#/components/schemas/ScimUserResource' description: The users on this page. Capitalised because SCIM defines it that way. description: A SCIM ListResponse envelope holding users. ScimPatchRequest: required: - schemas - Operations type: object properties: schemas: type: array items: type: string description: Always contains `urn:ietf:params:scim:api:messages:2.0:PatchOp`. Operations: type: array items: $ref: '#/components/schemas/ScimPatchOperation' description: The operations to apply, in order. Capitalised because SCIM defines it that way. description: A SCIM PatchOp envelope, the usual way an identity provider changes one attribute. ScimPatchOperation: required: - op type: object properties: op: enum: - add - remove - replace type: string description: The operation to apply. path: type: - 'null' - string description: Attribute path the operation targets. value: description: The new value, whose shape depends on the path. description: One operation inside a PatchOp. ScimEmail: required: - value - primary type: object properties: value: type: string description: The email address. primary: type: boolean description: Whether this is the address Routebase uses to identify the user. type: type: - 'null' - string description: Label the identity provider attached, such as work or home. description: One email address of a SCIM user. ScimGroupResource: required: - schemas - id - displayName - members - meta type: object properties: schemas: type: array items: type: string description: Always contains `urn:ietf:params:scim:schemas:core:2.0:Group`. id: type: string description: SCIM id of the group, assigned by Routebase. externalId: type: - 'null' - string description: The identifier the identity provider uses for this group. displayName: type: string description: Group name, which is what a group mapping matches on. members: type: array items: $ref: '#/components/schemas/ScimGroupMemberRef' description: Users in the group. Add and remove them with a PatchOp rather than by replacing the list. meta: description: Resource metadata written by Routebase, not by the identity provider. $ref: '#/components/schemas/ScimMeta' description: A SCIM 2.0 group with its members. Groups map onto Routebase teams. ScimName: type: object properties: givenName: type: - 'null' - string description: First name. familyName: type: - 'null' - string description: Last name. formatted: type: - 'null' - string description: The full name as the identity provider renders it. description: The structured name parts of a SCIM user. responses: ScimError: description: A SCIM error envelope. content: application/scim+json: schema: $ref: '#/components/schemas/ScimError' parameters: OrgSlug: name: OrgSlug in: path description: Slug of the organization, as shown in Settings. required: true schema: type: string ScimStartIndex: name: ScimStartIndex in: query description: 1-based index of the first result. Defaults to 1. schema: type: integer format: int32 ScimId: name: ScimId in: path description: SCIM id of the resource. required: true schema: type: string format: uuid ScimCount: name: ScimCount in: query description: Maximum number of results per page. Defaults to 100. schema: type: integer format: int32 securitySchemes: ApiKeyAuth: type: apiKey description: 'An organization API key, created under Settings then API Keys. Keys start with `rb_live_` and carry their own permission scopes, so a key only reaches what it was granted.' name: X-API-Key in: header ScimBearerAuth: type: http description: 'The SCIM token of the organization, issued when SCIM provisioning is enabled. It is separate from an API key and only unlocks the SCIM endpoints.' scheme: bearer x-routebase-folders: - name: API Specs children: [] - name: CI & Test Runs children: [] - name: Docs as Code children: [] - name: SCIM children: [] - name: Security children: []