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

# Authentication

> Authenticate server-side requests to Signup Risk API using first-party API keys.

Signup Risk API authenticates every request with a first-party API key presented as a Bearer token in the `Authorization` header. This is the only accepted credential transport — there are no query-parameter, cookie, or custom-header alternatives.

## Getting an API key

1. Create an account at [app.signuprisk.com/sign-up](https://app.signuprisk.com/sign-up).
2. Open the dashboard's **API Keys** page at [app.signuprisk.com/api-keys](https://app.signuprisk.com/api-keys).
3. Select **Create key**, give the key a name, choose its scopes, and optionally set an expiration.
4. Copy the full secret immediately. It is shown **once** at creation and cannot be retrieved again — the dashboard only ever displays a short preview afterwards.

Production keys begin with `eisk_live_...`; test keys begin with `eisk_test_...`. The environment is embedded in the key when it is created and cannot be changed later — a test key is rejected by the production API, and vice versa.

## Using the Bearer header

Send the key on every request:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

A minimal analysis request:

```bash theme={null}
curl https://api.signuprisk.com/v1/analyze-email \
  -X POST \
  -H "Authorization: Bearer $SIGNUP_RISK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"maria.garcia@protonmail.com"}'
```

Use a real, controlled address when testing. Documentation-reserved domains such as `example.com`, `example.org`, and `example.net` are special-use names that can never receive email, so the API deterministically returns `block` (risk score 100) for them.

## Keep API keys server-side

<Warning>
  Treat API keys as secrets. Anyone holding your key can consume your plan's
  quota and access your account's analysis features.
</Warning>

API keys belong in server environments: backend services, serverless functions, environment variables, secret managers, or CI/CD secrets where appropriate.

Do **not** place API keys in:

* browser JavaScript
* mobile app bundles
* public repositories
* URLs or query parameters

All Signup Risk API requests should originate from your backend. If you analyze signups from a client application, send the context to your own server first and call the API from there.

## Scopes

Every key carries a set of scopes that determine which endpoints it can call. New keys default to the `analyze` scope. Scopes are independent of plan entitlements — a key with the `bulk` scope still cannot use bulk endpoints unless the account's plan includes bulk processing.

| Scope      | Permits                               | Endpoints                                                                        |
| ---------- | ------------------------------------- | -------------------------------------------------------------------------------- |
| `analyze`  | Email analysis (default for new keys) | `POST /v1/analyze-email`, `POST /v1/analyze-email/batch`                         |
| `bulk`     | Asynchronous bulk jobs                | `POST /v1/bulk/jobs`, `GET /v1/bulk/jobs/{id}`, `GET /v1/bulk/jobs/{id}/results` |
| `webhooks` | Outbound webhook configuration        | All `/v1/webhooks` endpoints                                                     |

A key with no matching scope for a route receives `403` `INSUFFICIENT_SCOPE`. A key's scopes can be changed in the dashboard at any time.

## Authentication failures

The API returns distinct error codes so you can tell exactly what went wrong:

| Condition                                                             | Status                                    | `error.code`         |
| --------------------------------------------------------------------- | ----------------------------------------- | -------------------- |
| No `Authorization` header                                             | 401                                       | `MISSING_API_KEY`    |
| Malformed `Authorization` header                                      | 401                                       | `MALFORMED_API_KEY`  |
| Unknown or incorrect key (including a key from the wrong environment) | 401                                       | `INVALID_API_KEY`    |
| Revoked key                                                           | 401                                       | `REVOKED_API_KEY`    |
| Expired key                                                           | 401                                       | `EXPIRED_API_KEY`    |
| Key lacks the scope required by the route                             | 403                                       | `INSUFFICIENT_SCOPE` |
| The account owning the key is disabled                                | 403 on `/v1/analyze-email`, 401 elsewhere | `ACCOUNT_DISABLED`   |

None of these errors are retryable — fix the key or the header and retry. See the [Error Reference](/errors) for the complete catalog, including response bodies and remediation metadata.

## Key lifecycle

API keys are managed in the dashboard's **API Keys** page:

* **Create** — name the key, select scopes, optionally set an expiration. The secret is revealed once at creation.
* **Expiration** — optional per key. A key without an expiration never expires on its own.
* **Rotate** — issues a replacement key that inherits the name, scopes, and expiration of the original. The old key **remains active** after rotation so your integration keeps working: deploy the new key first, then revoke the old one.
* **Revoke** — immediately and permanently disables the key. Revocation is terminal; a revoked key cannot be re-enabled.
* **Last used** — the dashboard shows when each key was last used, so you can identify keys that are safe to retire.

## Next steps

<Card title="Understanding the response" icon="chart-bars" href="/understanding-the-response">
  Learn what the decision, checks, explanation, and metadata mean.
</Card>