Integration Tokens provide enterprise-grade, tenant-scoped access grants for embedding Xentree capabilities into external systems.Tokens are signed with RS256 using per-tenant key pairs. Each grant is short-lived, revocable, and bound to a specific set of scopes and an allowed origin.Core capabilities#
issue short-lived RS256 integration grants
verify token validity and check JTI revocation status
revoke a token immediately by JTI
rotate a token (revoke old, issue new in one atomic call)
expose the per-tenant JWKS endpoint for third-party verification
retrieve the public key fingerprint for out-of-band key pinning
admin observability of revoked tokens per tenant
Authentication and scopes#
All Integration Token endpoints require bearer or API key auth.Recommended API key scopes:integrations:read for verify, jwks, fingerprint
integrations:write for grant, revoke, rotate
GET /api/admin/integration-token-revocations) requires bearer auth with admin role.REST endpoints#
Issue integration grant#
Issue a short-lived RS256-signed JWT for a tenant.POST /api/integration/grant
{
"mode": "api",
"origin": "https://partner.example.com",
"scopes": ["profile:read", "quota:read"],
"ttlSeconds": 120
}
Verify integration token#
Check validity and revocation status of an integration JWT.POST /api/integration/verify
Revoke integration token#
Immediately invalidate a token by adding its JTI to the revocation list.POST /api/integration/revoke
Rotate integration token#
Revoke an existing token and issue a fresh one atomically.POST /api/integration/rotate
Tenant JWKS#
Return the active RS256 public key for the tenant in JWK Set format. Use this for third-party signature verification.GET /api/integration/jwks?tenantId={tenantId}
This endpoint is public — no auth required.
Public key fingerprint#
Return the SHA-256 fingerprint of the tenant's active public key for out-of-band key pinning.GET /api/integration/fingerprint?tenantId={tenantId}
This endpoint is public — no auth required.
Rate limits#
Grant and rotate operations are rate-limited per tenant per principal. When the limit is exceeded, the API returns 429 Too Many Requests with the following headers:| Header | Description |
|---|
X-RateLimit-Limit | Maximum requests allowed in the window |
X-RateLimit-Remaining | Remaining requests in the current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Retry-After | Seconds to wait before retrying |
Admin observability#
List revoked integration tokens for a specific tenant. Requires admin bearer token.GET /api/admin/integration-token-revocations?tenant_id={tenantId}&limit={limit}&offset={offset}
Modified at 2026-04-25 10:43:40
