# Secure Auth

> **Legacy.** This endpoint is kept for existing integrations. Use the current API reference for new work.

Secure Auth

- Endpoint: `GET https://api.returning.ai/api/secureAuth`
- Section: Legacy / Authentication
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Guide: generated from the published specification
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/legacy-authentication/secure-auth

## Authentication

- Header: `Authorization: Bearer <API_KEY>`

## Behaviour

**What it is for**

Secure Auth. Use this as part of password-based account authentication rather than broker system ingestion.

**How to use it**

Send a GET request to `/api/secureAuth` with the request body, query parameters, or multipart fields shown below. Authentication depends on the owning service. Keep credentials server-side and verify required permissions before production use.

**Successful response**

HTTP 200. The body follows the endpoint schema; many integration endpoints wrap the useful payload under `data` with `status` and `message`.

**Common error states**

- `400` invalid request body, query, ObjectId, pagination, file format, or missing required field.
- `401` missing, invalid, expired, or insufficient API key/token.
- `403` key is valid but cannot access this community/channel/user/resource, where supported by the service.
- `404` target resource, route, or community-scoped record was not found.
- `409` duplicate or conflicting state for create/update operations, where applicable.
- `500` unexpected Returning.AI service error.

## Request

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `accessLevel` | `string` | Yes | accessLevel query used by this endpoint. |
| `action` | `string` | Yes | action query used by this endpoint. |
| `userId` | `string[]` | Yes | user's username for authentication |
| `email` | `string` | No | user's email |
| `firstname` | `string` | No | user's first name |
| `lastname` | `string` | No | user's last name |
| `displayname` | `string` | No | user's displayname |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | API key. (`Bearer <API_KEY>`) |
| `apiKey` | `string` | No | apiKey header used by this endpoint. |
| `hostname` | `string` | No | hostname header used by this endpoint. |

### Example request

```bash
curl --request GET \
  --url 'https://api.returning.ai/api/secureAuth?accessLevel=0&action=login&userId=<Username>&email=<Email>&firstname=<First%20Name>&lastname=<Last%20Name>&displayname=<Display%20Name>' \
  --header 'Authorization: Bearer <API_KEY>'
```

## Response

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `error` | `boolean` | always | - |
| `loginUrl` | `string` | always | - |
| `sessionId` | `string` | always | - |

### Example response (200)

```json
{
  "error": false,
  "loginUrl": "https://cname.yourdomain.com/v2/app/loginApi/[API_KEY]/2?token= [token]&host=[cname.yourdomain.com]",
  "sessionId": "xxxxxxxxxxxxxxxxx"
}
```

## Errors

### Fix the request

| Status | Code | What to do |
| --- | --- | --- |
| 400 | - | Invalid request. Check required parameters, body fields, file format, pagination values, and ObjectId values. |
| 401 | - | Missing, invalid, expired, or insufficient API key/token. Older permission middleware may also return 401 for missing permissions. |

### Fix the data

| Status | Code | What to do |
| --- | --- | --- |
| 404 | - | The requested resource, route, community, channel, user, API key, status, or job was not found. |

### Retry with backoff

| Status | Code | What to do |
| --- | --- | --- |
| 500 | - | Unexpected Returning.AI service error. |

## Next step

- [Register user with password](https://docs.returning.ai/api-reference/legacy-authentication/register-user-with-password.md): `POST /auth/register`.