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, Postman testing).

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, and user version.

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/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

JWT Authentication Flow

Refresh Token

Logout

Get Current User

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

​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

Registration & Password Reset

Registration Flow

Password Reset Flow

Authentication Endpoints Reference

Security Best Practices