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

## Signup

```bash theme={null}
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={null}
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:

```json theme={null}
{
  "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={null}
curl --request POST 'https://modelslab.com/api/agents/v1/auth/logout' \
  --header 'Authorization: Bearer <agent_access_token>'
```

## Resend Verification

```bash theme={null}
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={null}
curl --request POST 'https://modelslab.com/api/agents/v1/auth/forgot-password' \
  --header 'Content-Type: application/json' \
  --data '{"email":"agent@example.com"}'
```

```bash theme={null}
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={null}
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={null}
{
  "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={null}
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={null}
{
  "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={null}
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>