Skip to main content

scim_admin

GET /orgs/{org_id}/scim-group-mappings​

Get the organization's SCIM group-to-role mappings.

Operation ID: getOrgScimGroupMappings · Service: gateway-api

Authentication​

  • consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters​

NameInRequiredTypeDescription
org_idpathyesstring

Responses​

StatusSchemaDescription
200ScimGroupMappingsGroup display names and their single role mappings.
defaultErrorEnvelopeError response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

PUT /orgs/{org_id}/scim-group-mappings​

Replace the organization's SCIM group-to-role mappings.

Each group_display_name occurs at most once and maps to exactly one non-owner role in this org. Invalid owner/duplicate mappings return 400 invalid_argument. Every target set must be a subset of the actor's effective org permissions, and so must the current role of every member whose assignment a change would replace (403 permission_denied otherwise). Changes reconcile existing SCIM membership assignments in request order; the last applied mapping wins conflicts and emits scim.group_conflict. Removing a mapping removes only its assignment contribution and restores the latest remaining contribution or the role that preceded SCIM group assignment. Permission cardinality never breaks ties. The complete replacement is atomic and audited.

Operation ID: putOrgScimGroupMappings · Service: gateway-api

Authentication​

  • consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters​

NameInRequiredTypeDescription
org_idpathyesstring

Request body​

ScimGroupMappings

Responses​

StatusSchemaDescription
200ScimGroupMappingsSaved group mappings.
defaultErrorEnvelopeError response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

POST /orgs/{org_id}/scim-token​

Mint the organization's SCIM bearer token.

The tsc_ bearer is shown only in the first 201 response, held in request memory only. Token storage uses prefix lookup plus peppered SHA-256. Explicit minting replaces the org's prior token; the prior token stops authenticating within 5 seconds. The default role defaults to member, must belong to the org, excludes owner, and cannot exceed the actor's effective org permissions. A token grants only SCIM access to this organization and cannot authenticate normal /v1 calls. Idempotency-Key is optional. Without the header, issuance follows the ordinary explicit mint and rotation flow. With the header, one successful issuance effect is retained for 24 hours in the addressed, server-validated organization, scoped by that organization, the caller's credential and environment, and the opaque key value. The non-secret issuance receipt stores neither plaintext bearer nor original response body. This operation alone is an exception to replaying a successful POST response: effect deduplication remains 24 hours, but the secret-bearing 201 response cannot be replayed. Every subsequent authorized request by the same caller with the same key in the same org, including after a lost first response or token revocation, returns 400 failed_precondition. error.details contains ScimTokenAlreadyIssuedDetail: type precondition_failure, reason scim_token_already_issued, and the original token_id and issued_at, with no bearer or additional fields. This acknowledges the recorded issuance. A duplicate runs no token RNG, mint, rotation, revocation, authorization generation increment or success audit, and never restores a revoked bearer. Current authentication, membership status, credential-family and operation-permission checks run before receipt lookup, and the request schema remains strictly validated. The original request wins for that key. A changed, schema-valid default-role body neither changes the recorded issuance nor mints another token. A different organization has an independent receipt scope and cannot observe this organization's receipt. After the receipt's 24-hour expiry, a new issuance with the same key may replace the expired receipt under the org lock. A new key requests an explicit new issuance and may rotate the active token through the ordinary mint operation. Another admin reusing the key gets their own issuance, an ordinary rotation. Every other POST follows the Idempotency-Key parameter.

Operation ID: createOrgScimToken · Service: gateway-api

Authentication​

  • consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters​

NameInRequiredTypeDescription
Idempotency-KeyheadernostringIdempotency key accepted by all POSTs (003 §1): 24 h dedup window, keyed per project. POSTs that are reads (batchSlotScores, scoreSlotEvent, deriveSlotBands, validateSourceRawPreset, sampleSource, watchEventFeedHeads and the preview operations: previewSourceMapping, previewCatalogMapping, previewLabel, previewPatternLabel, previewMarker, previewDatasetEligibility, previewSlotAudience, previewSharedCheckpointImport, previewSlotAtlasInquiry) accept the key but never replay a stored response: a retry with the same key is executed again (and metered again) against current data. A stored response that names an entity is removed when that entity is erased. A key that already answered answers only a retry of the request that stored its response: the same caller, environment, operation, path, query, scoping headers and body (a JSON body by its content, a gzip body by its inflated content). The same key with any other request is 409 already_exists with details[0].reason idempotency_key_reused, and that request is not run. The window holds no in-flight marker: two first requests sent at once can both run. A response stored by a release before this rule cannot be matched to its request and is refused the same way until it expires; send the request again with a new key. A body over 8 MiB (ingest: over its 5 MiB request limit) is run and its response is not stored. The ingest batch (POST /events) is the exception, except for an application's credentials: under a key that answered another batch it runs again, uncached, and its events' ids deduplicate them; so it does when its stored response cannot be checked. The operations that return a one-time secret store their response sealed: the stored copy opens only for the same key and credential, and one that cannot be opened is 409 idempotency_key_reused. While the server cannot check a stored response (it cannot read the key that checks it, for one), the request is 503 unavailable with Retry-After: retry with the same key. An operation whose handler claims the key itself answers the same 503, before it runs, while the key-hash pepper cannot be read; any other request sent with a key runs meanwhile, and its response is not stored.
org_idpathyesstring

Idempotency​

This operation accepts an Idempotency-Key header (003 §1): within 24 hours, keyed per project and caller, a retry of the same request gets the first response, and the same key with another request is 409 already_exists (idempotency_key_reused). See the Idempotency-Key parameter for the exceptions.

Request body​

ScimTokenCreateRequest

Responses​

StatusSchemaDescription
201ScimTokenCreatedNewly minted token; plaintext is shown once.
400ErrorEnvelopeInvalid request, or an authorized duplicate issuance acknowledged with failed_precondition and ScimTokenAlreadyIssuedDetail in error.details. The acknowledgment contains no bearer or original response body.
defaultErrorEnvelopeError response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

DELETE /orgs/{org_id}/scim-token​

Revoke the organization's SCIM token.

Token authentication fails with a SCIM 401 within 5 seconds. Existing provisioned users, role assignments and group mappings are retained.

Operation ID: revokeOrgScimToken · Service: gateway-api

Authentication​

  • consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters​

NameInRequiredTypeDescription
org_idpathyesstring

Responses​

StatusSchemaDescription
204—SCIM token revoked.
defaultErrorEnvelopeError response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

Errors​

Every non-2xx response uses the 003 §1 error envelope; error.request_id matches the X-Request-Id response header, and the HTTP status always matches error.code:

{
  "error": {
    "code": "invalid_argument",
    "details": [
      {
        "type": "field_violation"
      }
    ],
    "message": "human-readable",
    "request_id": "req_01hxample"
  }
}

Closed error-code set (003 §1): invalid_argument, unauthenticated, permission_denied, not_found, already_exists, failed_precondition, resource_exhausted, internal, unavailable.

resource_exhausted responses (HTTP 429) additionally carry retry_after_seconds. See ErrorEnvelope.