Authentication

The Curate-Me API uses JWT (JSON Web Tokens) for authentication. Access tokens are short-lived and refresh tokens allow you to obtain new access tokens without re-authenticating.

Token Lifetimes

Login

Authenticate with email and password.

POST /api/v1/auth/login

Request:

{
  "email": "user@example.com",
  "password": "securePassword123"
}

Response (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 1800
}

Refresh Token

Exchange a valid refresh token for a new access token.

POST /api/v1/auth/refresh

Request:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Response (200):

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 1800
}

Logout

Invalidate the current access and refresh tokens.

POST /api/v1/auth/logout

Headers:

Authorization: Bearer {access_token}

Request:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Response (204): No content.

Using Tokens

Include the access token in the Authorization header on all authenticated requests:

curl -X GET https://api.curate-me.ai/api/v1/user/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

B2B Organization Context

For B2B API requests, include the X-Org-ID header to specify the organization context. The middleware resolves organization identity in the following priority order:

1. JWT claims — org_id and org_role embedded in the token payload.
2. X-Org-ID header — Passed explicitly by the dashboard client.
3. URL path parameter — Extracted from /organizations/{org_id}/... routes.

curl -X GET https://api-admin.curate-me.ai/api/v1/admin/agents/status \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "X-Org-ID: org_xyz789"

B2B API Keys

For server-to-server integrations, you can create long-lived API keys instead of using JWT tokens.

Create an API Key

POST /api/v1/platform/api-keys

Headers:

Authorization: Bearer {access_token}
X-Org-ID: org_xyz789

Request:

{
  "name": "Production Integration",
  "scopes": ["agents:read", "workflows:read", "workflows:execute", "costs:read"]
}

Response (201):

{
  "id": "key_abc123",
  "name": "Production Integration",
  "key": "cm_sk_0123456789abcdef0123456789abcdef01234567",
  "scopes": ["agents:read", "workflows:read", "workflows:execute", "costs:read"],
  "created_at": "2026-01-15T10:30:00Z"
}

The full key value is only returned once at creation time. Store it securely.

Using API Keys

Pass the gateway key in the X-CM-API-Key header. The same key validates both the gateway proxy (https://api.curate-me.ai/v1/<provider>) and the admin REST surface — see docs/api/quickstart.md for the canonical gateway integration walkthrough.

curl -X GET https://api-admin.curate-me.ai/api/v1/admin/agents/status \
  -H "X-CM-API-Key: cm_sk_0123456789abcdef0123456789abcdef01234567"

API keys are scoped to a specific organization and do not require the X-Org-ID header.

The previous beta used cm_live_sk_ / cm_test_sk_ prefixes. Those keys are no longer accepted by the production gateway — re-issue a new key in Dashboard → Settings → API Keys if you are still holding one.