> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modelslab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Agent signup, login/logout, password reset, email verification, and token refresh endpoints for the control plane.

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

## Signup

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
  }'
```

## Login

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/agents-api/scopes).

Example response:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST 'https://modelslab.com/api/agents/v1/auth/logout' \
  --header 'Authorization: Bearer <agent_access_token>'
```

## Resend Verification

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST 'https://modelslab.com/api/agents/v1/auth/forgot-password' \
  --header 'Content-Type: application/json' \
  --data '{"email":"agent@example.com"}'
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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": "..."
  }
}
```

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

## Refresh Token

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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": "..."
  }
}
```

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

## Verification Compatibility Route

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET 'https://modelslab.com/verify/<verification_token>'
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.