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` selector
`POST`	`/api/agents/v1/auth/verify-email`	None	Verify email with `verification_code` (no browser required). Returns `access_token` + `api_key`
`POST`	`/api/agents/v1/auth/refresh`	Bearer token	Refresh/rotate access token without re-login
`POST`	`/api/agents/v1/auth/logout`	Bearer token	Revokes current token
`POST`	`/api/agents/v1/auth/logout-all`	Bearer token	Revokes all user tokens
`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
never

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