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

# Authentication

> Authenticate to our API so you can start using the sandbox.

As an admin user for your organization, you can manage your API keys in the Noyo web application. We recommend adding a sandbox API key for each developer working on the integration. Each developer should securely save a respective key's `CLIENT_ID` and `CLIENT_SECRET`. Later, when moving to production, create a separate API key with live-only permission. Save this key's `CLIENT_ID` and `CLIENT_SECRET` securely in your own production environment to interact with the Noyo API.

Once you have an API key, you can generate a short-lived access token (valid for \~10 minutes) using the `CLIENT_ID` and `CLIENT_SECRET` as the username/password combination in a Basic Authentication header.

Use the following curl snippet directly, or import it into API client software such as Postman:

```sh theme={"system"}
curl -X POST
 --header "Content-Type: application/json"
 --header "Authorization: Basic <Base64Encode(<CLIENT_ID>:<CLIENT_SECRET>)>"
 --data '{"grant_type": "client_credentials"}'
 https://accounts.noyo.com/auth/public/token
```

The response will include your `ACCESS_TOKEN`:

```json theme={"system"}
{
    "access_token": "<ACCESS_TOKEN>",
    "expires_in": 864000,
    "token_type": "Bearer"
}
```

Use this `ACCESS_TOKEN` in the Authorization header for each request you make to the Noyo API, like this request to get a list of groups for your organization in the sandbox:

```sh theme={"system"}
curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment-sandbox.noyo.com/api/v1/groups
```

You can make this request to test whether your token is working correctly. At this stage, you should have a sandbox group configured, which will be returned in this API result. You should get a `200` response to confirm a successful call:

```json theme={"system"}
{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "5d0b974b-2ee1-4d42-bf81-6715079b6a29",
            "version": "e3d63d18-b210-450a-bdda-fadba098e9c2",
            "created": 1631553366,
            "modified": 1631553366,
            "organization_id": "95e591f8-102d-4df9-8e9f-24e5c9b77d56",
            "name": "Your Sandbox Group Name",
            "sic_code": "",
            "dba_name": "",
            "federal_ein": ""
        }
    ]
}
```

## Authentication troubleshooting

For most authentication issues you will receive one of the following error messages. For any other issues, contact [support@noyo.com](mailto:support@noyo.com).

### Missing credentials

A JWT has not been supplied in the Authorization HTTP header. Ensure that the Authorization HTTP header reads `Bearer <JWT>`.

```json 401 Unauthorized theme={"system"}
{
    "code": 16,
    "message": "JWT validation failed: Missing or invalid credentials",
    "details": [
        {
            "@type": "type.googleapis.com/google.rpc.DebugInfo",
            "stackEntries": [],
            "detail": "auth"
        }
    ]
}
```

### Malformed JWT

The JWT has been truncated or altered in some way since it was originally acquired. Please double check the original HTTP response from [accounts.noyo.com/auth/public/token](https://accounts.noyo.com/auth/public/token).

```json 401 Unauthorized theme={"system"}
{
   "code": 16,
   "message": "JWT validation failed: The JWT cannot be validated with any of the public keys.",
   "details": [
       {
           "@type": "type.googleapis.com/google.rpc.DebugInfo",
           "stackEntries": [],
           "detail": "auth"
       }
   ]
}
```

### Expired token

The JWT has expired. We recommend requesting a new API token and re-attempting your original request. You can anticipate this issue by using the `expires_in` property returned along with any API token. The `expires_in` value is the number of milliseconds until the API token expires. A token refresh performed before that time could mitigate this issue.

```json 401 Unauthorized theme={"system"}
{
    "code": 16,
    "message": "JWT validation failed: TIME_CONSTRAINT_FAILURE",
    "details": [
        {
            "@type": "type.googleapis.com/google.rpc.DebugInfo",
            "stackEntries": [],
            "detail": "auth"
        }
    ]
}
```

# Authentication

[Using the API](/docs/introduction/getting-started/using-the-api)