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

# Authenticate API requests

> Learn how to send bearer tokens with Compute API requests and handle common authentication errors.

The Compute API uses bearer token authentication. Every request must include an API token in the `Authorization` header.

Bearer tokens let the API identify who is making the request and which Compute resources that user or organization can access.

\<Warning> Treat API tokens like passwords. Anyone with a valid token may be able to access or change Compute resources linked to that token. \</Warning>

## Send your token in the Authorization header

Add your token to each request like this:

```text theme={null}
Authorization: Bearer <your-api-token>
```

For example:

```text theme={null}
curl --request GET \
  --url "https://api.hivenet.com/v1/instances" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Accept: application/json"
```

## Use an environment variable

For local testing, you can store your token in an environment variable so you don’t paste it into every command.

```text theme={null}
export HIVENET_API_TOKEN="YOUR_API_TOKEN"
```

Then use it in your request:

```text theme={null}
curl --request GET \
  --url "https://api.hivenet.com/v1/instances" \
  --header "Authorization: Bearer $HIVENET_API_TOKEN" \
  --header "Accept: application/json"
```

<Tip>
  Environment variables are useful for local testing, but they’re not a full secrets-management system. For production workflows, store API tokens in the secret manager used by your deployment environment.
</Tip>

## Check that your token works

Use a read-only endpoint, such as [`GET /instances`](/public-api/endpoints/list-instances), to test authentication.

```text theme={null}
curl --request GET \
  --url "https://api.hivenet.com/v1/instances?size=1" \
  --header "Authorization: Bearer $HIVENET_API_TOKEN" \
  --header "Accept: application/json"
```

If the token is valid, the API returns `200 OK`.

A successful response may still contain an empty `data` array. That usually means the token works, but there are no matching resources visible to the account or organization.

## Understand access

A token can only access resources allowed by the user, organization, or access policy behind it.

If a request succeeds for one resource but fails for another, the token may be valid but may not have access to that specific resource.

For example:

* [`GET /instances`](/public-api/endpoints/list-instances) may return only instances visible to your account.
* [`GET /instances/{id}`](/public-api/endpoints/get-instance) may return `404` if the instance doesn’t exist or isn’t visible to your token.
* Actions such as [starting an instance](/public-api/endpoints/start-instance) or [terminating an instance](/public-api/endpoints/terminate-instance) may require access to that instance.

## Common authentication errors

| Status                  | What it means                                            | What to check                                                                                                                     |
| :---------------------- | :------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`      | The request is missing a valid token.                    | Check that the `Authorization` header exists and uses the `Bearer` format.                                                        |
| `403 Forbidden`         | The token is valid, but the request is not allowed.      | Check whether the account, organization, or token has access to the resource.                                                     |
| `404 Not Found`         | The resource wasn’t found or isn’t visible to the token. | Check the resource ID, or list resources first with an endpoint such as [`GET /instances`](/public-api/endpoints/list-instances). |
| `429 Too Many Requests` | Too many requests were sent in a short time.             | Wait before retrying. Use `Retry-After` when the response includes it.                                                            |

## Keep tokens safe

Follow these basic rules when working with API tokens:

* Don’t commit tokens to Git or other source control.
* Don’t paste tokens into public issues, chat messages, or shared documents.
* Don’t expose tokens in frontend code or mobile apps.
* Don’t store tokens in plain text if your tool supports encrypted secrets.
* Rotate tokens if they may have been exposed.
* Revoke tokens you no longer use.

Never put a Compute API token in client-side code. Anyone who can inspect the app or webpage may be able to copy the token.

## Rotate or revoke tokens

Rotate a token when you want to replace it with a new one. Revoke a token when it should stop working.

You should revoke a token when:

* A team member no longer needs access
* A script or integration has been retired
* A token was shared by mistake
* A device or environment that stored the token may be compromised

After revoking a token, update any scripts or integrations that still depend on it.

## Next step

Continue with [Work with instances](/public-api/work-with-instances) to understand how instance lifecycle states behave when you use the API.