Introspect the integration key.

GET

/integration/self

const url = 'https://shiftagent.example.com/integration/self';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://shiftagent.example.com/integration/self \
  --header 'Authorization: Bearer <token>'

Returns the calling key’s principal: its root tenant, granted scopes, and the registered per-tenant approver keys (public metadata only — key IDs and algorithms, never secret material). Lets an adapter verify its configuration and discover its root tenant without any local state.

Authorizations

integrationKey

Responses

200

The key principal.

application/json

The integration key’s identity, introspected.

object

object

required

string

Allowed value: integration_principal

key_id

required

The service key’s ID (not the secret).

string

name

required

Human-assigned key name.

string

root_tenant_id

required

Root of the key’s subtree — every tenant it provisions is a child of this tenant.

string

/^tnt_[A-Za-z0-9]+$/

scopes

required

Coarse grants, e.g. tenants:write, users:write, roles:write, repositories:write, conversations:read_all, conversations:write.

Array<string>

approver_keys

required

Approver keys registered for this integration’s tenants (public metadata only).

Array<object>

Public metadata of a registered per-tenant approver key (registered out-of-band; secret material never exposed).

object

key_id

required

Referenced by ApprovalSignature.key_id.

string

algorithm

required

Signature algorithm this key verifies.

string

Allowed values: hmac-sha256 ed25519

created_at

required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time

Examples

principal

Adapter service key introspection

{
  "object": "integration_principal",
  "key_id": "key_01hzx8int001",
  "name": "host-adapter",
  "root_tenant_id": "tnt_01hzx8root001",
  "scopes": [
    "tenants:write",
    "users:write",
    "roles:write",
    "repositories:write",
    "conversations:read_all",
    "conversations:write"
  ],
  "approver_keys": [
    {
      "key_id": "apk_01hzx8host001",
      "algorithm": "hmac-sha256",
      "created_at": "2026-07-01T12:00:00Z"
    }
  ]
}

401

Missing or invalid credentials — no bearer token, an unknown/revoked sk_int_ key, or an expired platform JWT.

application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object

type

required

Problem type URI (registry slug).

string format: uri-reference

title

required

Short, human-readable summary of the problem type.

string

status

required

HTTP status code.

integer format: int32

detail

Human-readable explanation specific to this occurrence.

string

instance

URI reference identifying this occurrence.

string format: uri-reference

request_id

Correlation ID for support and log lookup.

string

conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string

errors

On validation-error, field-level details.

Array<object>

object

pointer

required

JSON pointer to the offending field.

string

message

required

What failed.

string

Examples

unauthorized

Missing or invalid bearer token

{
  "type": "https://shiftagent.example.com/problems/insufficient-scope",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Provide a valid sk_int_ service key or platform JWT.",
  "request_id": "req_01hzx8auth001"
}