# auth.md

Not an agent? The human version of this page is https://decipon.com/developers.

You are an agent. This document tells you how to get a credential for the **Decipon API** (influence tactics detection for text and URLs) and how to use it. Follow the steps in order.

Decipon has **no unattended registration**. Credentials are API keys (credential type `api_key`). A key comes from a paid plan that a person completes in Stripe Checkout, or from a Decipon administrator. You can start the checkout and give the person the link; you cannot finish payment yourself.

API host: `https://api.decipon.com`. Public pages: `https://decipon.com`.

## Step 1 — Discover

A request to a protected endpoint without a credential gets `401` with:

```http
WWW-Authenticate: Bearer, X-API-Key
```

A revoked or unknown API key gets `401` with `WWW-Authenticate: X-API-Key`. An invalid or expired bearer token, or one whose account no longer exists, gets `401` with `WWW-Authenticate: Bearer`. These challenges carry no metadata URL. A `401` from the token endpoints in Step 4 (`/v1/auth/migrate` with a missing or unknown key, `/v1/auth/token/refresh` with a bad token) carries `WWW-Authenticate: Bearer resource_metadata="https://api.decipon.com/.well-known/oauth-protected-resource"`. The documents below are always at these fixed URLs.

- Protected Resource Metadata: `https://api.decipon.com/.well-known/oauth-protected-resource` (`authorization_servers`, `scopes_supported`, `bearer_methods_supported: ["header"]`).
- Authorization Server Metadata: `https://api.decipon.com/.well-known/oauth-authorization-server`. Its authorization-code flow (`/auth/login`) accepts only redirect URIs on a configured allow-list, by default those of the Decipon browser extension, so agents use Step 4 instead.
- MCP server card: `https://api.decipon.com/.well-known/mcp/server-card.json`. Agent catalog: `https://api.decipon.com/.well-known/ai-catalog.json`.

Some data needs no credential at all: the weekly source leaderboard (`GET /v1/leaderboard/weekly`), recent news analyses (`GET /v1/news/showcase`) and domain reputation (`GET /v1/reputation/domain/{domain}`).

## Step 2 — Pick a method

1. **Prepaid credits, no account.** Best for a one-off or small job. Each analysis uses credits from the balance. Go to Step 3a.
2. **Metered subscription.** For ongoing use, billed per call each month. Needs the person's email and name. Go to Step 3b.
3. **Key from an administrator.** If the person already has a Decipon API key, ask them for it and go to Step 4.

## Step 3 — Get an API key

### 3a. Prepaid credits

List the packages:

```http
GET /v1/credits/packages HTTP/1.1
Host: api.decipon.com
```

Response (200): `packages[]` with `id`, `name`, `credits`, `price_cents`, `description`.

Start a checkout. No authentication:

```http
POST /v1/credits/checkout HTTP/1.1
Host: api.decipon.com
Content-Type: application/json

{"package_id": "starter"}
```

Response (200):

```json
{
  "checkout_url": "https://checkout.stripe.com/...",
  "session_id": "cs_...",
  "package_id": "starter",
  "credits": 50
}
```

Give `checkout_url` to the person: "Open this link and pay to get a Decipon API key." After payment Stripe sends them to `https://api.decipon.com/credits/success`, which shows the new API key **once**, for up to one hour, together with an order reference. Ask the person to paste the key back to you. The purchase creates a customer with no email on file.

### 3b. Metered subscription

```http
POST /billing/checkout HTTP/1.1
Host: api.decipon.com
Content-Type: application/json

{"email": "person@example.com", "name": "Person or company name"}
```

Response (200): `{"checkout_url": "...", "session_id": "..."}`. Ask the person before you send their email. Give them `checkout_url`; after payment the API key is shown once on `https://api.decipon.com/billing/b2b-success`. Ask them to paste it back to you.

Plans and prices: https://decipon.com/pricing.

## Step 4 — Use the credential

Send the key in a header on every request:

```http
POST /v1/analyze HTTP/1.1
Host: api.decipon.com
X-API-Key: <api_key>
Content-Type: application/json

{"content": "Text to analyse"}
```

Other endpoints: `POST /v1/analyze/url` (`{"url": "..."}`), `POST /v1/analyze/batch`, `GET /v1/score/{content_hash}`. Full reference: https://api.decipon.com/docs and https://api.decipon.com/openapi.json.

MCP: the streamable-HTTP endpoint `https://api.decipon.com/mcp` takes the same `X-API-Key` header, or the bearer token below. Over MCP, a missing or invalid credential does not return HTTP `401`: the tool result comes back with `isError` set and a message containing `UNAUTHORIZED:` (the MCP SDK puts `Error executing tool <name>: ` in front of it), which points to the protected resource metadata (`/.well-known/oauth-protected-resource`).

To use `Authorization: Bearer` instead, exchange the key for tokens:

```http
POST /v1/auth/migrate HTTP/1.1
Host: api.decipon.com
X-API-Key: <api_key>
Content-Type: application/json

{"device_info": "my-agent"}
```

Response (200): `{"access_token": "...", "refresh_token": "...", "token_type": "Bearer", "expires_in": 900}`. Send `Authorization: Bearer <access_token>`. The access token lasts `expires_in` seconds (currently 15 minutes) and the refresh token 30 days. Read `expires_in` from each response rather than assuming a lifetime. The API key keeps working.

Refresh before the access token expires:

```http
POST /v1/auth/token/refresh HTTP/1.1
Host: api.decipon.com
Content-Type: application/json

{"refresh_token": "<refresh_token>"}
```

The response is a new token pair; the old refresh token stops working.

## Step 5 — Rotate, recover or revoke

Revoke a refresh token when you are done (always answers 204):

```http
POST /v1/auth/revoke HTTP/1.1
Host: api.decipon.com
Content-Type: application/json

{"refresh_token": "<refresh_token>"}
```

Replace a leaked API key. The old key stops working at once and the response field `api_key` holds the new one, shown once:

```http
POST /billing/keys/regenerate HTTP/1.1
Host: api.decipon.com
X-API-Key: <api_key>
```

Lost key from a credit purchase: the person can get a new one with the order reference from their receipt (the old key is revoked):

```http
POST /v1/recovery/order HTTP/1.1
Host: api.decipon.com
Content-Type: application/json

{"order_reference": "ORD-A7F3B2E1DEADBEEF"}
```

## Errors

| Status | Meaning | What to do |
| ------ | ------- | ---------- |
| 401 | Missing, invalid or revoked key or token | For a bearer token, refresh once. Otherwise ask the person for a valid key. |
| 402 | Prepaid credits used up, or subscription suspended for non-payment | Tell the person. Credits: `POST /v1/credits/purchase` with the key and `{"package_id": "..."}` returns a `checkout_url` for a top-up. Subscription: every request with the key now gets 402, so the person contacts support@decipon.com to restore access. While payment is overdue but before suspension, responses carry an `X-Payment-Warning` header, and during that time `GET /billing/portal` with the key returns a Stripe portal link where the person updates payment. |
| 429 | Rate limit or monthly quota reached | Wait for `Retry-After` seconds when the header is present; otherwise wait about a minute, then retry. |
| 5xx | Temporary server error | Retry with exponential backoff. |

Do not retry a 4xx other than 429 with the same request.
