# Authentication

> Use, rotate, and protect App API Keys.

Canonical page: https://rpc.aurpay.net/docs/authentication

Every public Gateway request uses an App API Key. The Host selects the chain, network, and protocol; the API Key selects the App. One valid Key can access enabled, routed Gateways that belong to that App.

## In brief

- Send the App API Key as `Authorization: Bearer <key>` for server-side calls, or use the dashboard URL that carries it in the first path segment.
- When both locations are present, their values must match exactly.
- Treat the complete Key and any URL containing it as secrets; rotate or revoke a Key after suspected exposure.

## API Key in the Authorization header

This placement is recommended for server-side applications because it keeps the API Key out of URLs and access logs:

```bash
curl 'https://ether-jsonrpc.<gateway-domain>' \
  -H 'Authorization: Bearer <app_api_key>' \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

`Authorization` must contain exactly `Bearer <key>`.

## API Key in the URL path

Put the API Key in the first path segment when an SDK requires a complete RPC URL:

```text
https://ether-jsonrpc.<gateway-domain>/<app_api_key>
https://tron-httpapi.<gateway-domain>/<app_api_key>/wallet/getnowblock
```

> Protect the complete URL as a secret when the API Key is carried in its path. Apply the same redaction rules to proxy logs, browser history, and monitoring data.

If a request carries the API Key in both the path and the `Authorization` header, the two values must match exactly.

## Key states and rotation

- **Active**: accepted normally.
- **Grace**: the previous Key remains accepted during a rotation grace period.
- **Expired**: no longer accepted after the grace period.
- **Revoked**: invalid immediately.

Open **App Settings → Access keys** to view Key states, rotate the active Key, or revoke an existing Key. Recommended rotation sequence: create the new Key, update every application instance, verify the new Key, keep the previous Key in Grace until clients have switched, then revoke it.

Keep the App and Account active and use an Active or Grace Key. The authentication status codes are listed in [Errors and recovery](https://rpc.aurpay.net/docs/errors.md).

## Security guidance

- Store Keys in a Secret Manager or runtime environment variable.
- Keep Keys out of Git history, frontend bundles, and mobile bundles.
- Log an internal Key ID, not the complete Key or a URL containing it.
- Rotate and revoke immediately after suspected exposure.

## Related

- [JSON-RPC](https://rpc.aurpay.net/docs/json-rpc.md)
- [Authenticate requests](https://rpc.aurpay.net/docs/management-api/authentication.md)
- [Errors and recovery](https://rpc.aurpay.net/docs/errors.md)