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

# UGMail Management API Authentication with Bearer Tokens

> UGMail uses Bearer token authentication for all Management API requests. Learn how to retrieve your token and use it securely in your app.

Every request to the UGMail Management API must be authenticated with a tenant-scoped Bearer token. This token identifies your account, enforces access control, and ensures that operations you perform are isolated to your tenant. There are no API keys, OAuth flows, or rotating secrets to manage — one token covers all Management API endpoints.

## Get your Bearer token

Sign in to your UGMail account at [my.ugmail.co](https://my.ugmail.co), then navigate to **Settings → API Connection**. Your Bearer token is displayed on that page. Click the copy button to grab it.

<Warning>
  Your Bearer token grants full management access to your UGMail tenant — including the ability to delete domains and mailboxes. Never commit it to version control, hardcode it in client-side code, or share it in public forums. Store it in an environment variable or a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or your CI/CD platform's secret store.
</Warning>

## Use the token in requests

Include the token in the `Authorization` header of every Management API request using the `Bearer` scheme:

```
Authorization: Bearer YOUR_TOKEN
```

The examples below show how to do this in curl, Python, and Node.js.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://mail.ugmail.co/api/principal" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json"
  ```

  ```python Python theme={null}
  import requests

  TOKEN = "YOUR_TOKEN"  # load from environment in production

  response = requests.get(
      "https://mail.ugmail.co/api/principal",
      headers={
          "Authorization": f"Bearer {TOKEN}",
          "Content-Type": "application/json",
      },
  )

  response.raise_for_status()
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const TOKEN = process.env.UGMAIL_TOKEN; // always load from env

  const response = await fetch("https://mail.ugmail.co/api/principal", {
    method: "GET",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
    },
  });

  if (!response.ok) {
    throw new Error(`UGMail API error: ${response.status} ${response.statusText}`);
  }

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Error responses

If your token is missing, malformed, or invalid, the API returns one of the following error responses.

| Status code        | Meaning                                                                                                                                                                                                                      |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | The `Authorization` header is missing, the token is malformed, or the token is not recognised. Check that you copied the full token and that the header is formatted correctly.                                              |
| `403 Forbidden`    | The token is valid but does not have permission to perform the requested operation. This can occur if your account plan does not include a particular feature or if you are attempting to access another tenant's resources. |

A `401` response body looks like this:

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Missing or invalid Bearer token."
}
```

<Note>
  The Management API does not use session cookies or HTTP Basic auth. If you have previously used another email API that relies on username/password authentication, note that UGMail's Management API exclusively uses Bearer tokens. SMTP, IMAP, and other protocol connections do use per-mailbox username/password credentials — see the [Protocols Overview](/protocols/overview) for details.
</Note>

## Rotate your token

If you believe your token has been compromised or you want to rotate it as part of a routine security practice, return to **Settings → API Connection** in [my.ugmail.co](https://my.ugmail.co) and generate a new token. Your previous token is invalidated immediately upon rotation.

<Tip>
  Update every environment — local development, staging, and production — in quick succession after rotating. Because the old token is invalidated immediately, any service still using it will begin returning `401 Unauthorized` errors until you deploy the new token.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Walk through creating a domain and mailbox using your token.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Browse every authenticated endpoint in the Management API.
  </Card>
</CardGroup>