> ## 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.

# API Authentication: Using Bearer Tokens with UGMail

> All UGMail Management API requests require a Bearer token in the Authorization header. Get your token from Settings → API Connection at my.ugmail.co.

Every request to the UGMail Management API must be authenticated using a Bearer token. There are no API keys, no OAuth flows, and no session cookies — just a single token you pass in the `Authorization` header on every call. This keeps integration simple and predictable across any language or HTTP client.

## Obtaining Your Token

Your Bearer token lives in the UGMail dashboard:

<Steps>
  <Step title="Log in to your account">
    Go to [my.ugmail.co](https://my.ugmail.co) and sign in.
  </Step>

  <Step title="Open Settings">
    Click **Settings** in the left-hand navigation.
  </Step>

  <Step title="Navigate to API Connection">
    Select **API Connection** from the Settings menu. Your token is displayed here. Copy it to a secure location.
  </Step>
</Steps>

## Using Your Token

Pass your token in the `Authorization` header with the `Bearer` scheme on every API request:

```
Authorization: Bearer YOUR_TOKEN
```

### Example Request

```bash theme={null}
curl "https://mail.ugmail.co/api/principal" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Replace `YOUR_TOKEN` with the token you copied from **Settings → API Connection**. This pattern is the same regardless of which endpoint you call — authentication never changes.

## Authentication Errors

If your request is not authenticated correctly, the API returns one of the following errors:

| Status             | Cause                                                             | Resolution                                                               |
| ------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `401 Unauthorized` | Token is missing, malformed, or expired                           | Check that the `Authorization` header is present and correctly formatted |
| `403 Forbidden`    | Token is valid but does not have access to the requested resource | Verify you are accessing resources that belong to your account           |

A `401` response means the API could not identify you at all. A `403` response means it identified you successfully but determined you are not permitted to perform that operation.

## Keeping Your Token Secure

<Warning>
  Never expose your Bearer token in client-side code, public repositories, or frontend applications. Anyone who obtains your token has full access to your UGMail account's resources. Store it in an environment variable or a secrets manager, and never commit it to version control.
</Warning>

Best practices for token security:

* Store your token in environment variables (e.g., `UGMAIL_API_TOKEN`) rather than hardcoding it
* Use a secrets manager (such as AWS Secrets Manager, HashiCorp Vault, or Doppler) in production environments
* Restrict access to the token to only the services and team members that need it
* Rotate your token if you suspect it has been compromised

## Rotating Your Token

If your token is exposed or you want to issue a fresh one, you can regenerate it at any time:

<Steps>
  <Step title="Go to Settings → API Connection">
    Navigate to [my.ugmail.co](https://my.ugmail.co) → **Settings** → **API Connection**.
  </Step>

  <Step title="Click Regenerate Token">
    Select **Regenerate Token**. A new token is issued immediately.
  </Step>

  <Step title="Update your integrations">
    Replace the old token in all of your applications, scripts, and environment variables with the new one. The old token is invalidated instantly.
  </Step>
</Steps>

<Tip>
  Rotate your token on a regular schedule as a security best practice — especially before and after team member changes.
</Tip>