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

# Authentication

> How to authenticate with the VMArea Public API using API tokens.

The VMArea Public API uses API tokens exclusively. There is no OAuth flow, no session cookie, and no JWT for public API access.

## API token format

All tokens begin with the prefix `vmk_`. Pass the token in the `x-api-key` request header:

```http theme={null}
x-api-key: vmk_...
```

## Obtaining a token

<Steps>
  <Step title="Open API Keys settings">
    Navigate to **Settings → API Keys** in the [VMArea dashboard](https://vmarea.com/dashboard/settings/api-keys).
  </Step>

  <Step title="Create a new key">
    Click **New API Key** and give it a descriptive name (e.g., `deploy-pipeline`).
  </Step>

  <Step title="Select scopes">
    Choose the [scopes](/en/scopes) you need — grant only what is required.
  </Step>

  <Step title="Set an expiry (optional)">
    Tokens without an expiry remain valid until manually revoked. Setting an expiry is recommended for CI/CD tokens.
  </Step>

  <Step title="Copy the secret">
    Click **Create**.

    <Warning>
      The secret is shown only once and cannot be retrieved again. Copy it immediately.
    </Warning>
  </Step>
</Steps>

## Token lifecycle

```
Created → In use → [Expired | Revoked]
```

* A token is active from the moment of creation.
* If an expiry was set, the token is automatically rejected after that date/time.
* You can revoke any token from the dashboard at any time.
* Deleting a token is permanent; requests using it will receive `401 Unauthorized`.

## Scopes

Tokens carry only the permissions you granted at creation. A request that requires a scope the token does not hold returns `403 Forbidden`. See [Scopes & permissions](/en/scopes) for the full list.

## Usage examples

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.vmarea.com/api/public/v1/vms \
    -H "x-api-key: $VMAREA_TOKEN"
  ```

  ```js JavaScript theme={null}
  const res = await fetch("https://api.vmarea.com/api/public/v1/vms", {
    headers: { "x-api-key": process.env.VMAREA_TOKEN },
  });
  ```
</CodeGroup>

## Security guidance

* **Never commit tokens to source control.** Use environment variables or a secrets manager.
* **Use the minimum scope set** needed for the integration.
* **Rotate tokens regularly**, especially after any suspected exposure.
* **Set an expiry** for tokens used in CI/CD environments.
* Treat your `vmk_` token with the same care as a password.