Authentication

The co-mind.ai API supports two authentication methods. Both use the Authorization: Bearer <token> header.

Personal Access Tokens (Recommended)
JWT Authentication

PATs are long-lived tokens for programmatic API access. They are the recommended method for integrations, scripts, CI/CD pipelines, and any non-interactive usage.Token format: cmnd_<tokenId>.<secret>

# Use a PAT for all API calls
curl https://your-instance/v1/models \
  -H "Authorization: Bearer cmnd_your-token-here"

Advantages:

Long-lived (up to 365 days)
Fine-grained scopes limit access to only what’s needed
Can be rotated without downtime
No refresh flow required

See API Tokens for full management details.

JWT tokens are short-lived and ideal for interactive sessions (web apps, ad-hoc testing with curl).

Access tokens expire in 1 hour
Use the refresh token to obtain new access tokens
Best suited for browser-based applications

curl https://your-instance/v1/models \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

JWT Authentication Flow

POST /v1/auth/login

curl -X POST https://your-instance/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

import requests

response = requests.post("https://your-instance/v1/auth/login", json={
    "email": "user@example.com",
    "password": "your_password"
})
tokens = response.json()

const response = await fetch("https://your-instance/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "user@example.com",
    password: "your_password"
  })
});
const tokens = await response.json();

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "user_abc123",
    "email": "user@example.com",
    "privileges": ["admin", "auditView"],
    "groupMemberships": ["engineering", "admins"],
    "userVersion": 3
  }
}

LDAP/AD routing: If the user’s email domain matches an IdP configuration, the login request is automatically routed to the configured LDAP/AD directory for authentication. No client-side changes are needed.

POST /v1/auth/sso

curl -X POST https://your-instance/v1/auth/sso \
  -H "Content-Type: application/json" \
  -d '{
    "oid": "entra-object-id",
    "tid": "entra-tenant-id",
    "upn": "user@example.com"
  }'

Refresh Token

POST /v1/auth/refresh

curl -X POST https://your-instance/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your_refresh_token"}'

The refresh endpoint validates the user’s current status — suspended or disabled users are blocked from refreshing tokens.

Logout

POST /v1/auth/logout

curl -X POST https://your-instance/v1/auth/logout \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "your_access_token",
    "refresh_token": "your_refresh_token"
  }'

Get Current User

GET /v1/auth/me

curl https://your-instance/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns user info including privileges, group memberships, current tenant scope, and user version. Accepts either a JWT or a PAT. Response (multi-tenant user):

{
  "id": "user_abc123",
  "email": "user@example.com",
  "currentTenantId": "tenant_a_id",
  "groupMemberships": [
    { "groupId": "tenant_a_id", "role": "Admin",  "status": "active" },
    { "groupId": "tenant_b_id", "role": "Member", "status": "active" }
  ],
  "privileges": ["admin"],
  "systemTenantId": "system_tenant_id"
}

currentTenantId — the tenant this session (or PAT) is currently scoped to.
groupMemberships[] — every tenant the user belongs to. Read directly from the database, so a PAT (which is bound to one tenant) still returns the full list.

Multi-tenant Sessions

A user may belong to more than one tenant (workspace). An interactive JWT session can be switched between the user’s tenants; each switch mints a fresh token pair scoped to the target tenant.

PATs cannot be switched — a PAT is bound to a single tenant at issuance. To operate against another tenant, mint a new PAT under that tenant. See API Tokens → Tenant scope.

Switch Tenant

POST /v1/auth/switch-tenant

curl -X POST https://your-instance/v1/auth/switch-tenant \
  -H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "target_tenant_id"}'

Response (new token pair, scoped to the target tenant):

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

The prior access token is blacklisted immediately on switch and will return 401 on the next call. Clients must replace their cached access_token and refresh_token with the pair returned above.

tenant_id may be a sub-organization id; the server normalizes it to the tenant root for isolation. Sub-organizations remain addressable by their own id on endpoints that take one.
Membership is verified — the caller must be a member of the target tenant. System administrators may switch into any tenant (recorded as an override in the audit log).
Rate-limited per user; do not switch in tight loops.

Full flow — list tenants, then switch

curl -X POST https://your-instance/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"..."}'
# → keep access_token and refresh_token

List memberships and see the active tenant

curl https://your-instance/v1/auth/me \
  -H "Authorization: Bearer $ACCESS" \
  | jq '{currentTenantId, memberships: [.groupMemberships[] | {groupId, role, status}]}'

If currentTenantId is null, the session has not yet picked an active tenant — pick one in the next step.

Switch to a chosen tenant

curl -X POST https://your-instance/v1/auth/switch-tenant \
  -H "Authorization: Bearer $ACCESS" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":"'"$TARGET_TENANT"'"}'
# → REPLACE $ACCESS and $REFRESH with the values from the response

Confirm the switch landed

curl https://your-instance/v1/auth/me \
  -H "Authorization: Bearer $ACCESS" | jq '.currentTenantId'
# → matches the tenant_id you switched to

Registration & Password Reset

Registration Flow

Check Registration

curl "https://your-instance/v1/auth/check-registration?email=user@example.com"

curl -X POST https://your-instance/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secure_password", "name": "User Name"}'

Confirm Email

curl -X POST https://your-instance/v1/auth/confirm \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "code": "123456"}'

Password Reset Flow

Request Reset

curl -X POST https://your-instance/v1/auth/password-reset-request \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Execute Reset

curl -X POST https://your-instance/v1/auth/password-reset \
  -H "Content-Type: application/json" \
  -d '{"token": "reset_token", "new_password": "new_secure_password"}'

Authentication Endpoints Reference

Endpoint	Method	Auth	Purpose
`/v1/auth/login`	POST	None	Login and get JWT tokens
`/v1/auth/sso`	POST	None	SSO login (Microsoft Entra ID)
`/v1/auth/refresh`	POST	None	Refresh JWT access token
`/v1/auth/me`	GET	Bearer	Get current user info
`/v1/auth/switch-tenant`	POST	JWT	Switch active tenant scope; returns a new token pair
`/v1/auth/logout`	POST	None	Revoke JWT tokens
`/v1/auth/check-registration`	GET	None	Check if email is registered
`/v1/auth/register`	POST	None	Register new user
`/v1/auth/confirm`	POST	None	Confirm email with auth code
`/v1/auth/change-password`	POST	JWT	Change password
`/v1/auth/password-reset-request`	POST	None	Request password reset
`/v1/auth/password-reset`	POST	None	Execute password reset
`/v1/auth/admin/set-password`	POST	Service	Admin set user password
`/v1/auth/users/{userId}`	DELETE	Service	Delete user with cascade

Security Best Practices

Use PATs for integrations

PATs are long-lived and scoped — much better than JWTs for automated workflows. Reserve JWTs for interactive sessions.

Always use HTTPS

Never send tokens over HTTP. All production deployments should enforce TLS.

Store secrets securely

Use environment variables or secret managers (AWS Secrets Manager, HashiCorp Vault) — never commit tokens to source control.

Use minimal scopes

Only request the permissions you need. A read-only integration should not have write scopes.

Rotate tokens periodically

Use the POST /v1/api-tokens/{id}/rotate endpoint for seamless rotation without downtime.

Revoke unused tokens

Delete tokens that are no longer needed using DELETE /v1/api-tokens/{id}.

Never commit tokens to source control

Use .env files, CI/CD secrets, or secret managers instead.

Getting Started

Guides

API Walkthrough

JWT Authentication Flow

Refresh Token

Logout

Get Current User

Multi-tenant Sessions

Switch Tenant

Full flow — list tenants, then switch

Registration & Password Reset

Registration Flow

Password Reset Flow

Authentication Endpoints Reference

Security Best Practices

​JWT Authentication Flow

​Login

​SSO Login (Microsoft Entra ID)

​Refresh Token

​Logout

​Get Current User

​Multi-tenant Sessions

​Switch Tenant

​Full flow — list tenants, then switch

​Registration & Password Reset

​Registration Flow

​Password Reset Flow

​Authentication Endpoints Reference

​Security Best Practices

JWT Authentication Flow

Login

SSO Login (Microsoft Entra ID)

Refresh Token

Logout

Get Current User

Multi-tenant Sessions

Switch Tenant

Full flow — list tenants, then switch

Registration & Password Reset

Registration Flow

Password Reset Flow

Authentication Endpoints Reference

Security Best Practices