External Auth Claim Mappings

List Claim Mappings

get

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

sort_bystring[]OptionalDefault: []

limitinteger · max: 200OptionalDefault: 50

continuation_tokenanyOptional

statusstring · enum · nullableOptionalPossible values:

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokenanyOptional

422

Validation Error

application/json

get/v1/{workspace_id}/external-auth-claim-mappings

GET /v1/{workspace_id}/external-auth-claim-mappings HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "claim_namespace": "text",
      "claim_key": "text",
      "external_value": "text",
      "external_role_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "active",
      "changed_by": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Create Claim Mapping

post

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

claim_namespacestring · min: 1 · max: 64RequiredPattern: ^[a-z][a-z0-9_.:-]{0,63}$

claim_keystring · min: 1 · max: 64RequiredPattern: ^[a-z][a-z0-9_.:-]{0,63}$

external_valuestring · min: 1 · max: 256Required

external_role_idstring · uuidRequired

Responses

201

Successful Response

application/json

idstring · uuidRequired

claim_namespacestringRequired

claim_keystringRequired

external_valuestringRequired

external_role_idstring · uuidRequired

statusstring · enumRequiredPossible values:

changed_bystring · uuid · nullableOptional

created_atstring · date-timeRequired

409

An active mapping for this claim tuple already exists

422

Validation Error

application/json

post/v1/{workspace_id}/external-auth-claim-mappings

POST /v1/{workspace_id}/external-auth-claim-mappings HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 127

{
  "claim_namespace": "text",
  "claim_key": "text",
  "external_value": "text",
  "external_role_id": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "claim_namespace": "text",
  "claim_key": "text",
  "external_value": "text",
  "external_role_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "changed_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-01-01T00:00:00.000Z"
}

Resolve Preview Claim Mappings

post

Dry-run the SAME resolver the per-turn path uses — read-only, never writes.

Returns the mapped internal roles (id + name), the effective unioned active role grants, and the count of unmapped input atoms. Requires Workspace.view.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

Responses

200

Successful Response

application/json

unmapped_claim_countintegerRequired

422

Validation Error

application/json

post/v1/{workspace_id}/external-auth-claim-mappings/resolve-preview

POST /v1/{workspace_id}/external-auth-claim-mappings/resolve-preview HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "auth_claims": [
    {
      "namespace": "text",
      "key": "text",
      "value": "text"
    }
  ]
}

{
  "roles": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  ],
  "grants": [
    {
      "resource_type": "integration_endpoint",
      "resource_key": "text",
      "access": "read"
    }
  ],
  "unmapped_claim_count": 1
}

Get Claim Mapping

get

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

mapping_idstring · uuidRequired

Responses

200

Successful Response

application/json

idstring · uuidRequired

claim_namespacestringRequired

claim_keystringRequired

external_valuestringRequired

external_role_idstring · uuidRequired

statusstring · enumRequiredPossible values:

changed_bystring · uuid · nullableOptional

created_atstring · date-timeRequired

404

External auth claim mapping not found

422

Validation Error

application/json

get/v1/{workspace_id}/external-auth-claim-mappings/{mapping_id}

GET /v1/{workspace_id}/external-auth-claim-mappings/{mapping_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "claim_namespace": "text",
  "claim_key": "text",
  "external_value": "text",
  "external_role_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "changed_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-01-01T00:00:00.000Z"
}

Supersede Claim Mapping

post

Supersede an active mapping (immutable history) — flip active → superseded.

POST verb (not DELETE): the row persists and the superseded item is returned so the caller sees the final state. 404 if there is no active row for the id.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

mapping_idstring · uuidRequired

Responses

200

Successful Response

application/json

idstring · uuidRequired

claim_namespacestringRequired

claim_keystringRequired

external_valuestringRequired

external_role_idstring · uuidRequired

statusstring · enumRequiredPossible values:

changed_bystring · uuid · nullableOptional

created_atstring · date-timeRequired

404

Active external auth claim mapping not found

422

Validation Error

application/json

post/v1/{workspace_id}/external-auth-claim-mappings/{mapping_id}/supersede

POST /v1/{workspace_id}/external-auth-claim-mappings/{mapping_id}/supersede HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "claim_namespace": "text",
  "claim_key": "text",
  "external_value": "text",
  "external_role_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "active",
  "changed_by": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-01-01T00:00:00.000Z"
}

PreviousRole Grants NextConfig

Last updated 1 day ago

Was this helpful?