Authentication - ModelsLab

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.

​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