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

# Authentication

> Getting, using and refreshing tokens with your API key.

The Noyax API uses JWT **access tokens**. You get a token from the Noyax auth service with your API key and send it in the `Authorization` header of every request.

```http theme={null}
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImFwaSIs...
```

## Flow

```mermaid theme={null}
sequenceDiagram
    participant S as Your server
    participant A as Noyax Auth
    participant N as Noyax API
    S->>A: POST /ApiAuth/login (OrgName, ApiKey)
    A-->>S: AccessToken + RefreshToken
    S->>N: Request (Bearer AccessToken)
    N-->>S: 200 OK
    Note over S,N: Token expires
    S->>N: Request (expired token)
    N-->>S: 401 invalid_token
    S->>A: POST /ApiAuth/refresh (AccessToken, RefreshToken)
    A-->>S: New AccessToken + new RefreshToken
```

## Getting a token

<ParamField body="OrgName" type="string" required>
  Your organization name, issued by Noyax.
</ParamField>

<ParamField body="ApiKey" type="string" required>
  Your API key.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://app.noyax.com/services/bb_auth_service/api/ApiAuth/login \
    -H "Content-Type: application/json" \
    -d '{ "OrgName": "YOUR_ORG_NAME", "ApiKey": "YOUR_API_KEY" }'
  ```

  ```json Response theme={null}
  {
    "Data": {
      "AccessToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImFwaSIs...",
      "RefreshToken": "q3Jv1mYt8Rk0bXw2LzH5nD7sPfA9cGe4..."
    },
    "Success": true,
    "Message": null
  }
  ```
</CodeGroup>

If the credentials are wrong or your API license has expired, the auth service returns **401** (`Invalid API credentials.`, `ApiKey expired.`).

## Refreshing a token

Access tokens are short-lived (a matter of minutes). When a token expires, the API responds with:

```http theme={null}
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The token expired"

{
  "Success": false,
  "ResultCode": "0102",
  "Message": "Token has expired. Obtain a new token using the refresh token.",
  "Errors": [
    { "Code": "0102", "Message": "Token has expired. Obtain a new token using the refresh token." }
  ]
}
```

Get a new pair with the old access token and the refresh token:

```bash theme={null}
curl -X POST https://app.noyax.com/services/bb_auth_service/api/ApiAuth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "AccessToken": "EXPIRED_TOKEN", "RefreshToken": "REFRESH_TOKEN" }'
```

The response has the same shape as the login response.

<Warning>
  **Every login and refresh issues a new refresh token and invalidates the previous one.** An API key has only one valid refresh token at a time. If several servers or processes use the same key, manage the token in one place and share it. Otherwise a refresh in one process invalidates the refresh token of the others.
</Warning>

## Recommended practice

* Keep the token in memory or in a shared cache. Do not log in for every request.
* Refresh shortly before the token's `exp` claim, or refresh once when you get `401 invalid_token` and retry the request.
* If refreshing fails (`Invalid refresh token.`), log in again.

## Token contents

The access token carries the settings of your API key, captured when the token is issued:

| Claim | Meaning                                                           |
| ----- | ----------------------------------------------------------------- |
| `P`   | Module permissions. See [Permissions](/en/v1/guides/permissions)  |
| `ARC` | Daily request limit. See [Rate limits](/en/v1/guides/rate-limits) |
| `exp` | Token expiry (Unix time)                                          |

<Info>
  If the permissions or daily limit of your key change, the change takes effect **when you get a new token**.
</Info>