Authentication

Endpoints

Method	Endpoint	Auth	Notes
`POST`	`/api/agents/v1/auth/signup`	None	Create user, create Stripe customer, send verification email
`POST`	`/api/agents/v1/auth/login`	None	Returns Bearer token. Supports `token_expiry` and `scopes`
`POST`	`/api/agents/v1/auth/verify`	None	Verify email with `verification_code` (no browser required). Returns `access_token` + `api_key`
`POST`	`/api/agents/v1/auth/google-sign-in`	None	Sign in with a Google ID token. Returns Bearer token
`GET`	`/api/agents/v1/auth/scopes`	None	Lists every requestable scope and what it grants
`POST`	`/api/agents/v1/auth/logout`	Bearer token	Revokes current token. Never scope-gated
`POST`	`/api/agents/v1/auth/logout-all`	Bearer token	Revokes all user tokens. Requires `tokens:write`
`GET`	`/api/agents/v1/auth/tokens`	Bearer token	Lists tokens with their granted scopes. Requires `tokens:read`
`DELETE`	`/api/agents/v1/auth/tokens/{id}`	Bearer token	Revokes one token. Requires `tokens:write`
`POST`	`/api/agents/v1/auth/tokens/revoke-others`	Bearer token	Revokes every token except the current one. Requires `tokens:write`
`POST`	`/api/agents/v1/auth/switch-account`	Bearer token	Issues a token for another account in your team. Requires `tokens:write`
`POST`	`/api/agents/v1/auth/resend-verification`	None	Resends verification email
`POST`	`/api/agents/v1/auth/forgot-password`	None	Sends password reset email
`POST`	`/api/agents/v1/auth/reset-password`	None	Resets password with token
`GET`	`/verify/{token}`	None	Compatibility verification endpoint

curl --request POST 'https://modelslab.com/api/agents/v1/auth/signup' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "agent@example.com",
    "password": "secret123",
    "name": "Agent Runner"
  }'

curl --request POST 'https://modelslab.com/api/agents/v1/auth/login' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "agent@example.com",
    "password": "secret123",
    "device_name": "orchestrator-prod",
    "token_expiry": "1_month"
  }'

Supported token_expiry values:

1_week
1_month (default)
3_months
6_months
1_year
never

Account policy may cap what you asked for. Check token_lifetime_capped and expires_at in the response rather than assuming you got the lifetime you requested. Login also accepts an optional scopes array to mint a least-privilege token. Omit it and the token is issued with *. See Token Scopes. Example response:

{
  "data": {
    "access_token": "<bearer-token>",
    "token_type": "Bearer",
    "token_expiry": "1_month",
    "expires_at": "2026-03-21T09:30:00Z",
    "user": {
      "id": 123,
      "name": "Agent Runner",
      "email": "agent@example.com",
      "username": "agent",
      "verified": true
    },
    "api_key": "<default-api-key-or-null>"
  },
  "error": null,
  "meta": {
    "request_id": "..."
  }
}

Logout

curl --request POST 'https://modelslab.com/api/agents/v1/auth/logout' \
  --header 'Authorization: Bearer <agent_access_token>'

Resend Verification

curl --request POST 'https://modelslab.com/api/agents/v1/auth/resend-verification' \
  --header 'Content-Type: application/json' \
  --data '{"email":"agent@example.com"}'

Forgot / Reset Password

curl --request POST 'https://modelslab.com/api/agents/v1/auth/forgot-password' \
  --header 'Content-Type: application/json' \
  --data '{"email":"agent@example.com"}'

curl --request POST 'https://modelslab.com/api/agents/v1/auth/reset-password' \
  --header 'Content-Type: application/json' \
  --data '{
    "email":"agent@example.com",
    "token":"<reset-token>",
    "password":"new-secret123",
    "password_confirmation":"new-secret123"
  }'

Verify Email (Headless)

Verify a user’s email address using the verification_code from the verification email. This is the headless alternative to clicking the browser verification link, returning an access_token and api_key directly.

curl --request POST 'https://modelslab.com/api/agents/v1/auth/verify-email' \
  --header 'Content-Type: application/json' \
  --data '{
    "verification_code": "<code-from-verification-email>"
  }'

Example response:

{
  "data": {
    "message": "Email verified successfully.",
    "access_token": "<bearer-token>",
    "token_type": "Bearer",
    "expires_at": "2026-03-21T09:30:00Z",
    "user": {
      "id": 123,
      "name": "Agent Runner",
      "email": "agent@example.com",
      "username": "agent",
      "verified": true
    },
    "api_key": "<default-api-key-or-null>"
  },
  "error": null,
  "meta": {
    "request_id": "..."
  }
}

Use this endpoint in headless agent flows to avoid browser-based verification entirely. The verification_code is the token embedded in the verification email link.

Refresh Token

Rotate the current access token without re-authenticating with email/password. The old token is revoked and a new one is issued.

curl --request POST 'https://modelslab.com/api/agents/v1/auth/refresh' \
  --header 'Authorization: Bearer <agent_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "token_expiry": "1_month",
    "device_name": "orchestrator-prod"
  }'

Example response:

{
  "data": {
    "access_token": "<new-bearer-token>",
    "token_type": "Bearer",
    "token_expiry": "1_month",
    "expires_at": "2026-03-21T09:30:00Z",
    "message": "Token refreshed successfully. Previous token has been revoked."
  },
  "error": null,
  "meta": {
    "request_id": "..."
  }
}

Both token_expiry and device_name are optional. If omitted, the new token defaults to 1_month expiry and inherits the previous token name.

Verification Compatibility Route

curl --request GET 'https://modelslab.com/verify/<verification_token>'

This route exists for compatibility and supports browser redirect flow as well as JSON response mode.

Get Started

MCP Web API

Agents API (Control Plane)

Client SDKs

Guides

Endpoints

Logout

Resend Verification

Forgot / Reset Password

Verify Email (Headless)

Refresh Token

Verification Compatibility Route

​Endpoints

​Signup

​Login

​Logout

​Resend Verification

​Forgot / Reset Password

​Verify Email (Headless)

​Refresh Token

​Verification Compatibility Route

Endpoints

Signup

Login

Logout

Resend Verification

Forgot / Reset Password

Verify Email (Headless)

Refresh Token

Verification Compatibility Route