Skip to main content

​
Authentication

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

​
JWT Authentication Flow

​
Login

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"
  }'
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.

​
SSO Login (Microsoft Entra ID)

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

1

Check Registration

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

Register

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"}'
3

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

1

Request Reset

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

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

EndpointMethodAuthPurpose
/v1/auth/loginPOSTNoneLogin and get JWT tokens
/v1/auth/ssoPOSTNoneSSO login (Microsoft Entra ID)
/v1/auth/refreshPOSTNoneRefresh JWT access token
/v1/auth/meGETBearerGet current user info
/v1/auth/logoutPOSTNoneRevoke JWT tokens
/v1/auth/check-registrationGETNoneCheck if email is registered
/v1/auth/registerPOSTNoneRegister new user
/v1/auth/confirmPOSTNoneConfirm email with auth code
/v1/auth/change-passwordPOSTJWTChange password
/v1/auth/password-reset-requestPOSTNoneRequest password reset
/v1/auth/password-resetPOSTNoneExecute password reset
/v1/auth/admin/set-passwordPOSTServiceAdmin set user password
/v1/auth/users/{userId}DELETEServiceDelete user with cascade

​
Security Best Practices

PATs are long-lived and scoped — much better than JWTs for automated workflows. Reserve JWTs for interactive sessions.
Never send tokens over HTTP. All production deployments should enforce TLS.
Use environment variables or secret managers (AWS Secrets Manager, HashiCorp Vault) — never commit tokens to source control.
Only request the permissions you need. A read-only integration should not have write scopes.
Use the POST /v1/api-tokens/{id}/rotate endpoint for seamless rotation without downtime.
Delete tokens that are no longer needed using DELETE /v1/api-tokens/{id}.
Use .env files, CI/CD secrets, or secret managers instead.