Auth service

API index•/auth, /api-keys, /roles

Authentication, session lifecycle, API key management, roles, step-up, and break-glass controls.

Use this when you need sign-in, token lifecycle, privileged operations, or scoped API key management.

Endpoints

Service surface

POST

/auth/sso/login

Starts the OAuth/SSO login flow (e.g. Google). Email/password sign-in uses POST /auth/login instead.

Public

Initiate sign-in through the provider redirect.

curl -X POST "$API_BASE/auth/sso/login" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "google" }'

GET

/auth/callback

Completes the OAuth or SSO callback.

Public

Callback

The provider redirects back with a code.

curl "$API_BASE/auth/callback?code=<oauth-code>"

POST

/auth/refresh

Exchanges a refresh token for a new access token.

Refresh token

Refresh

Use a refresh token to obtain a new session token.

curl -X POST "$API_BASE/auth/refresh" \
  -H "Authorization: Bearer <refresh-token>"

POST

/auth/revoke

Revokes a session or token.

Bearer token

Revoke session

Explicitly invalidate a session or token.

curl -X POST "$API_BASE/auth/revoke" \
  -H "Authorization: Bearer <token>"

POST

/auth/step-up

Requests elevated authentication for sensitive operations.

Bearer token

Step-up

Request step-up before privileged actions.

curl -X POST "$API_BASE/auth/step-up" \
  -H "Authorization: Bearer <token>"

POST

/auth/break-glass/request

Starts a break-glass access request.

Bearer token

Break glass

Request emergency access.

curl -X POST "$API_BASE/auth/break-glass/request" \
  -H "Authorization: Bearer <token>"

GET

/api-keys

Lists API keys for the current tenant.

Bearer token

List API keys

List scoped keys for the tenant.

curl -H "Authorization: Bearer <jwt>" "$API_BASE/api-keys"

POST

/api-keys

Creates a new API key with scopes, namespaces, and IP restrictions.

Bearer token

Create API key

Create a scoped key for automation.

curl -X POST "$API_BASE/api-keys" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My integration",
    "scopes": ["memories:read", "memories:write"],
    "namespaces": ["default"],
    "ips": ["203.0.113.10"]
  }'

POST

/api-keys/{id}/rotate

Rotates an API key and returns the new secret once.

Bearer token

Rotate API key

Rotation returns a new one-time secret.

curl -X POST "$API_BASE/api-keys/<key-id>/rotate" \
  -H "Authorization: Bearer <jwt>"

DELETE

/api-keys/{id}

Revokes an API key.

Bearer token

Revoke API key

Delete access for a compromised key.

curl -X DELETE "$API_BASE/api-keys/<key-id>" \
  -H "Authorization: Bearer <jwt>"

GET

/roles

Lists roles visible to the authenticated principal.

Bearer token + RBAC

List roles

Read the caller's visible roles.

curl -H "Authorization: Bearer <jwt>" "$API_BASE/roles"

GET

/roles/{name}

Returns a role by name.

Bearer token + RBAC

Get role

Fetch a specific role by name.

curl -H "Authorization: Bearer <jwt>" "$API_BASE/roles/admin"

GET

/auth/tenants

Lists all tenants accessible to the authenticated user.

Bearer token

List tenants

Read tenants for the current user.

curl -H "Authorization: Bearer <jwt>" "$API_BASE/auth/tenants"

POST

/auth/tenants

Creates a new tenant with the given name.

Bearer token

Create tenant

Provision a new tenant.

curl -X POST "$API_BASE/auth/tenants" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp" }'

GET

/auth/gettenant

Returns the user's primary tenant (the first tenant in their membership).

Bearer token

Get tenant

Read the user's primary tenant.

curl -H "Authorization: Bearer <jwt>" "$API_BASE/auth/gettenant"

Request example

Create an API key

Scoped key creation is the most common developer-facing auth operation.

curl -X POST "$API_BASE/api-keys" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My integration",
    "scopes": ["memories:read", "memories:write"]
  }'

Base path

/auth, /api-keys, /roles

Schemas

OpenAPI-style field tables

API key create request

Payload used by POST /api-keys.

Field	Type	Required	Description
name	string	required	Human-readable key label.
scopes	string[]	required	Allowed capabilities.
namespaces	string[]	optional	Optional namespace restrictions.
ips	string[]	optional	Optional IP allowlist.

API key response

Returned from list, create, rotate, and revoke flows.

Field	Type	Required	Description
key_id	uuid	required	Key identifier.
secret	string	create/rotate only	One-time secret value.
status	"active" \| "revoked"	list only	Current key state.

Tenant object

Fields returned by the tenant list, create, and gettenant endpoints.

Field	Type	Required	Description
tenant_id	uuid	required	Unique tenant identifier.
name	string	required	Human-readable tenant name.
plan	string	required	Billing plan (e.g. free, pro, enterprise).
status	string	required	Tenant lifecycle status.
created_at	RFC3339 timestamp	optional	Creation timestamp.

Create tenant request

Payload used by POST /auth/tenants.

Field	Type	Required	Description
name	string	required	Name for the new tenant.

Response examples

What the API returns

List API keys

The list endpoint wraps keys in a top-level keys array.

{
  "keys": [
    {
      "key_id": "2b7e1b83-2f86-4cd1-9a8f-d7cb5efb2fe0",
      "name": "My integration",
      "scopes": ["memories:read", "memories:write"],
      "created_at": "2026-04-10T12:00:00Z",
      "last_used_at": null,
      "status": "active"
    }
  ]
}

Create API key

The create and rotate endpoints return the secret exactly once.

{
  "key_id": "2b7e1b83-2f86-4cd1-9a8f-d7cb5efb2fe0",
  "secret": "cme_live_...",
  "tenant_id": "2f2f0ce7-8f35-4d1c-9c1e-1f7f7fd00a48",
  "name": "My integration",
  "scopes": ["memories:read", "memories:write"]
}

Rotate / revoke behavior

Rotate returns the new secret; revoke returns a simple status payload.

rotate: { "key_id": "2b7e1b83-2f86-4cd1-9a8f-d7cb5efb2fe0", "secret": "cme_live_..." }
revoke: { "status": "revoked" }

List tenants

Returns an array of tenants accessible to the user.

{
  "tenants": [
    {
      "tenant_id": "2f2f0ce7-8f35-4d1c-9c1e-1f7f7fd00a48",
      "name": "Acme Corp",
      "created_at": "2026-04-01T00:00:00Z",
      "is_default": true
    }
  ]
}

Create tenant

Returns the newly created tenant object.

{
  "tenant_id": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "name": "Acme Corp",
  "created_at": "2026-05-07T12:00:00Z",
  "is_default": false
}

Get default tenant

Returns the user's current default tenant.

{
  "tenant_id": "2f2f0ce7-8f35-4d1c-9c1e-1f7f7fd00a48",
  "name": "Acme Corp",
  "is_default": true
}

Notes

Implementation notes

Create, rotate, and revoke operations are guarded by bearer auth and tenant context.
Step-up authentication is required for sensitive lifecycle actions in the portal.
The auth service routes are defined in cmd/auth-service/main.go and cmd/auth-service/apikey_handlers.go.