# auth.md — Authentication for useapi.net

> Machine- and human-readable guide to authenticating with the useapi.net API.
> useapi.net uses a long-lived, per-account **static API token** sent as a Bearer
> header. A single token authenticates every REST API request, and the REST API
> accepts nothing else. The 11 hosted MCP servers take the same token, and also
> offer OAuth 2.1 sign-in for apps that can't send a custom header, such as the
> Claude app and ChatGPT (see "MCP servers: OAuth sign-in" below).

## Scheme

| Property | Value |
|---|---|
| Type | Static API token (long-lived bearer credential) |
| Transport | HTTPS only |
| API base URL | `https://api.useapi.net` |
| Auth header | `Authorization: Bearer user:TOKEN` |
| Token format | `user:<digits>-<alphanumeric>` (e.g. `user:12345-abcdefghijklmnop`) |
| Scope | One token authorizes every API under the user's subscription |

## How to authenticate

Send every request to `https://api.useapi.net` with an `Authorization` header
carrying your token, prefixed by `Bearer `:

```
Authorization: Bearer user:12345-abcdefghijklmnop
```

Notes that prevent the common `401`:

- Send the **complete** token, including the literal `user:` prefix and the
  alphanumeric suffix. Do not truncate it to just the digits.
- Do **not** URL-encode the token.
- On the REST API the token is the only credential — there is no client
  id/secret, refresh token, or login endpoint. OAuth access tokens from the MCP
  sign-in below are refused by the REST API.

### Example request

```bash
curl https://api.useapi.net/v2/account \
  -H "Authorization: Bearer user:12345-abcdefghijklmnop"
```

`GET https://api.useapi.net/v2/account` returns the account's subscription
status and configured AI-service accounts, and is the documented way to verify
that a token works.

## How a human obtains a token

A token is issued to a person, not minted programmatically by an agent:

1. Purchase a useapi.net subscription at `https://useapi.net/docs/subscription`.
   Enter a valid email — the token is delivered there.
2. Open the welcome email and follow its verification link to activate the
   account.
3. The activated page displays the account's useapi.net API token. Copy the
   complete `user:...` string.

Full walkthrough: `https://useapi.net/docs/start-here/setup-useapi`

An AI agent cannot self-register or self-provision a token. A human completes
the steps above once, then supplies the resulting token to the agent.

## What this token authorizes

A single token works across every useapi.net service API (Runway,
Kling, MiniMax / Hailuo, Google Flow, Google Vids, Muse, Gemini Notebook, Dreamina, Mureka,
FlowMusic, TemPolor, PixVerse, InsightFaceSwap, ACE Music, and account management). Per-API request and response
shapes differ — only the authentication header is shared.

## MCP servers: OAuth sign-in

The hosted MCP servers (Streamable HTTP) are:

- `https://api.useapi.net/v1/google-flow/mcp`
- `https://api.useapi.net/v1/muse/mcp`
- `https://api.useapi.net/v1/acemusic/mcp`
- `https://api.useapi.net/v1/google-vids/mcp`
- `https://api.useapi.net/v1/gemini-notebook/mcp`
- `https://api.useapi.net/v1/dreamina/mcp`
- `https://api.useapi.net/v1/kling/mcp`
- `https://api.useapi.net/v2/pixverse/mcp`
- `https://api.useapi.net/v1/mureka/mcp`
- `https://api.useapi.net/v1/flowmusic/mcp`
- `https://api.useapi.net/v1/minimax/mcp`

Each accepts either credential in the `Authorization` header:

1. The static API token, `Authorization: Bearer user:12345-abcdefghijklmnop`,
   exactly as on the REST API. Claude Code, Cursor, VS Code and other clients
   that send a custom header keep using it.
2. An OAuth access token for that server, which the app gets through MCP's
   authorization flow (OAuth 2.1, PKCE `S256` required, scope `mcp`).

| Property | Value |
|---|---|
| Authorization server (issuer) | `https://useapi.net` |
| Issuer metadata (RFC 8414) | `https://useapi.net/.well-known/oauth-authorization-server` |
| Protected resource metadata (RFC 9728) | `https://api.useapi.net/.well-known/oauth-protected-resource/v1/<service>/mcp` |
| Authorization endpoint | `https://api.useapi.net/v1/oauth/authorize` |
| Token and revocation endpoint | `https://api.useapi.net/v1/oauth/token` |
| Dynamic client registration (RFC 7591) | `https://api.useapi.net/v1/oauth/register`, public clients only (`token_endpoint_auth_method: "none"`) |
| Client ID Metadata Documents | Supported |
| Redirect URIs | The Claude app (`https://claude.ai/api/mcp/auth_callback`, `https://claude.com/api/mcp/auth_callback`), ChatGPT (`https://chatgpt.com/connector_platform_oauth_redirect`, `https://chatgpt.com/connector/oauth/<id>`) and loopback (`http://localhost` or `http://127.0.0.1`, any port) only |
| Scope | `mcp` |
| Access token lifetime | 1 hour, renewed with the refresh token |
| Refresh token | Lapses after 90 days without use |
| Resource | One MCP server per connection: a token works only at the server it was issued for |

A request to an MCP URL without a token gets `401` with this header, which
starts discovery:

```
WWW-Authenticate: Bearer realm="useapi.net", resource_metadata="https://api.useapi.net/.well-known/oauth-protected-resource/v1/<service>/mcp", scope="mcp"
```

The protected resource metadata names the authorization server
`https://useapi.net`, whose metadata lists the endpoints above.

At the consent step, the authorization endpoint shows a useapi.net page where the
person pastes their useapi.net API token (the one from the welcome email, see
`https://useapi.net/docs/start-here/setup-useapi`) and clicks Allow. A human
still obtains the API token as described above, and OAuth never issues one.
Resetting the API token (`https://useapi.net/docs/account-management/post-account-token-reset`)
disconnects every app connected with it.

Setup steps for the Claude app and ChatGPT are on each server's docs page, for
example `https://useapi.net/docs/api-kling-v1/mcp`.

## Discovery for agents

- API base URL: `https://api.useapi.net`
- Service index (LLM-readable): `https://useapi.net/llms.txt`
- Combined documentation: `https://useapi.net/llms-full.txt`
- Agent integration guide: `https://useapi.net/llm-tools/claude-code-skill.txt`
- API catalog (RFC 9727 linkset): `https://useapi.net/.well-known/api-catalog`
- MCP servers (Agentic Resource Discovery): `https://useapi.net/.well-known/ard.json`
- OAuth issuer metadata (MCP servers only): `https://useapi.net/.well-known/oauth-authorization-server`
- Verify a token: `GET https://api.useapi.net/v2/account`

## Support

Questions about access or tokens: `https://useapi.net/docs/support`

