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

> ## Agent Instructions
> Use Gomobile customer-facing vocabulary.
> Do not infer support for internal, hidden, experimental, or unreleased features.

# Authenticate with an API key

> Create an organization API key and send it safely in server-to-server requests.

Gomobile API keys are long-lived machine credentials for server-to-server integrations. Only organization owners and administrators can manage keys in the customer interface.

## Create a key

**1. Open API keys**

In the Gomobile sidebar, select **API keys**.

**2. Create the key**

Choose **Create key**, enter a unique descriptive name, and select an Admin, Manager, or Agent role. Choose an expiration that matches your organization's security policy.

**3. Store the secret immediately**

Copy the secret into an approved server-side secret manager. Gomobile shows the complete value only once.

**4. Acknowledge storage**

Confirm that you copied the secret, then close the dialog.

> [!WARNING]
>
> If you lose the secret, you cannot reveal it again. Create a replacement key, update the integration, verify it, and revoke the old key.

## Send the key

Send the secret in the `X-API-Key` header on every API request:

```http theme={null}
X-API-Key: <your-secret-key>
```

Use the API base URL supplied by Gomobile, including the `/api` prefix. Available operations depend on the key’s role and your organization’s enabled services.

For copy-ready environment variables, pagination, error handling, and safe test guidance, see [API basics](https://docs.gomobile.ma/developers/api-basics.md).

## Manage the key lifecycle

From **API keys**, you can:

* search by name or masked identifier;
* see role, status, last use, creator, and expiration;
* change its name or expiration;
* disable it temporarily and enable it again;
* revoke it permanently.

The assigned role is fixed. Create a new key when the integration needs a different role.

## Rotate a key safely

**1. Create a replacement**

Give the new key a name that identifies the integration and rotation period.

**2. Update the server secret**

Replace the credential in the integration's secret manager without committing it to source control.

**3. Verify requests**

Confirm that the integration succeeds with the replacement key.

**4. Revoke the old key**

Revoke the previous credential only after all workloads have moved to the replacement.

## Authentication failures

| Symptom | Check |
| - | - |
| Request is unauthenticated | The header is exactly `X-API-Key`, the value is the secret, and the key has not been revoked |
| Request was working and now fails | Check whether the key expired or was disabled |
| Request is forbidden | Check the key’s role and your organization’s enabled services |
| Secret cannot be recovered | Create a replacement; the complete secret is shown only at creation |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.