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

# Partner Auth

> Add NanoGPT-powered AI to your product while keeping your own user accounts, brand, and UI.

## Overview

Partner Auth lets your backend authenticate one of your users to NanoGPT without giving you direct access to NanoGPT account credentials or API keys.

You send a short-lived JWT signed by your backend. NanoGPT verifies it, maps your user ID to a normal NanoGPT account behind the scenes, and runs requests against that linked account.

The same partner user always maps to the same NanoGPT account.

<Note>
  Partner Auth is available by request. Contact NanoGPT to configure your partner slug, JWT audience, public signing key, redirect allowlist, and optional commercial settings before production use.
</Note>

## How It Works

```mermaid theme={null}
flowchart TD
  A["Your app user"] --> B["Your backend"]
  B -->|"Signs short-lived JWT"| C["NanoGPT API"]
  C -->|"Verifies your public key"| D["Partner Auth"]
  D -->|"Maps your user ID"| E["Linked NanoGPT account"]
  E --> F["Balance, usage, models, and billing"]
  F --> C
  C --> B
  B --> A
```

Your backend owns the private key. NanoGPT stores only the public key.

## What NanoGPT Configures

Before launch, NanoGPT configures:

* Your partner slug, for example `example`
* Your JWT audience, for example `nanogpt-partner-api:example`
* Your public signing key and key ID, for example `example-2026-04`
* Allowed browser redirect URLs for SSO
* Optional referral revenue share
* Optional partner tiers for discounts and request-access allowance rules

You keep the private key in your own secret manager.

## JWT Requirements

Every partner-authenticated request uses:

```http theme={null}
Authorization: Bearer <partner-signed JWT>
```

JWT header:

```json theme={null}
{
  "alg": "ES256",
  "kid": "example-2026-04"
}
```

JWT claims:

```json theme={null}
{
  "iss": "example",
  "aud": "nanogpt-partner-api:example",
  "sub": "your-opaque-user-id",
  "iat": 1770000000,
  "exp": 1770000300,
  "jti": "unique-request-id",
  "scope": ["request:create"]
}
```

Rules:

* Use `ES256` or `RS256`.
* `exp - iat` must be at most 5 minutes.
* `jti` must be unique per request token.
* `sub` must be your stable user identifier, opaque to NanoGPT.
* Do not send emails, names, or other personal data as `sub`.
* NanoGPT stores `HMAC-SHA256(sub)`, not the raw `sub`.
* Create JWTs on your backend only. Never sign tokens in the browser.

Optional tier claim:

```json theme={null}
{
  "tier": "premium"
}
```

NanoGPT validates the tier against your active partner tier configuration.

## Scopes

Use the smallest scope needed for each request.

| Scope | Purpose |
| - | - |
| `request:create` | Create AI requests such as chat, image, video, or audio requests |
| `session:web` | Create a one-time browser login link |
| `balance:read` | Read the linked user's NanoGPT balance |
| `deposit:create` | Create a deposit or top-up request |
| `usage:read` | Read usage for the JWT `sub` |
| `usage:read:any` | Backend-only scope to read usage for another `subject` query param |

## Send AI Requests

Use a partner JWT instead of a NanoGPT API key.

```bash theme={null}
curl -X POST "https://nano-gpt.com/api/v1/chat/completions" \
  -H "Authorization: Bearer $PARTNER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "Summarize this article in three bullets." }
    ]
  }'
```

The JWT must include:

```text theme={null}
request:create
```

The request is charged to the linked NanoGPT account for the JWT `sub`.

See also: [Chat Completion](/api-reference/endpoint/chat-completion), [Image Generation](/api-reference/image-generation), and [Video Generation](/api-reference/video-generation).

## Check User Balance

```bash theme={null}
curl -X POST "https://nano-gpt.com/api/check-balance" \
  -H "Authorization: Bearer $PARTNER_JWT"
```

The JWT must include:

```text theme={null}
balance:read
```

The response includes the linked user's balance and deposit details.

## Initiate A Top-Up

Partner-authenticated top-ups are not limited to Nano. The same linked NanoGPT account can be funded through enabled NanoGPT deposit methods, including:

* Native Nano direct deposits: read the linked user's `nanoDepositAddress` from the balance response and show that address to the user. No deposit call is needed; incoming Nano credits automatically. See [Check User Balance](#check-user-balance).
* Stablecoins and major chains (`usdc`, `usdt`, `sol`, `eth`, `base`, `arbitrum`, `polygon`, `bnb`, `trx`): call `POST /api/transaction/create/boomfi/{ticker}` to create a hosted payment for the linked user.
* Crypto invoice or swap deposits (`btc`, `btc-ln`, `ltc`, `ltc-mweb`, `xmr`, `doge`, `dash`, `zec`): call `POST /api/transaction/create/{ticker}`.
* Card deposits where enabled for the partner integration.

Deposit creation, status polling, and cancellation all require the `deposit:create` scope on the partner JWT.

Available methods can change by region, provider status, amount, and partner configuration. Ask NanoGPT which top-up methods should be enabled for your integration before launch.

For invoice-style payment methods, create the payment request for the linked user with the ticker route:

```bash theme={null}
curl -X POST "https://nano-gpt.com/api/transaction/create/btc-ln" \
  -H "Authorization: Bearer $PARTNER_JWT" \
  -H "Content-Type: application/json" \
  -d '{"amount": 0.00001}'
```

The JWT must include:

```text theme={null}
deposit:create
```

NanoGPT resolves the user from the JWT `sub` and returns deposit details for that linked account. For ticker-specific limits, request bodies, status polling, and supported payment methods, see [Crypto Deposits](/api-reference/endpoint/crypto-deposits).

## Browser SSO

Use browser SSO when you want to send a user from your product into NanoGPT already signed in as the linked account.

Create a one-time login link:

```bash theme={null}
curl -X POST "https://nano-gpt.com/api/partners/auth/login-links" \
  -H "Authorization: Bearer $PARTNER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_url": "https://your-product.example/account/ai"
  }'
```

The JWT must include:

```text theme={null}
session:web
```

NanoGPT returns:

```json theme={null}
{
  "url": "https://nano-gpt.com/auth/partner/example?token=...",
  "expiresAt": "2026-05-07T12:00:00.000Z"
}
```

The login token is one-time use and short-lived. Absolute redirect URLs must be allowlisted.

## Read User Usage

Read usage for the JWT `sub`:

```bash theme={null}
curl "https://nano-gpt.com/api/partners/users/usage?duration=month" \
  -H "Authorization: Bearer $PARTNER_JWT"
```

The JWT must include:

```text theme={null}
usage:read
```

Backend service usage lookup for a specific user:

```bash theme={null}
curl "https://nano-gpt.com/api/partners/users/usage?subject=your-opaque-user-id&duration=month" \
  -H "Authorization: Bearer $PARTNER_SERVICE_JWT"
```

If `subject` differs from the JWT `sub`, the JWT must also include:

```text theme={null}
usage:read:any
```

Use `usage:read:any` only from trusted backend services.

## Funding Options

NanoGPT supports user-funded usage by default:

* Each linked user has their own NanoGPT balance.
* Your product can show the user's balance and top-up options.
* If the linked user has no balance, paid requests return the normal insufficient-balance response.
* If configured, your partner account can earn referral revenue from user-funded top-ups.

Partner tiers can configure usage discounts once NanoGPT enables tiers for your integration:

* `free`: no discount
* `basic`: 5% discount
* `premium`: 10% discount

Tier names and discount rates are configurable per partner.

## Request-Access Funding Features

Some funding options require NanoGPT approval and explicit configuration before they can be used:

* Free starter prompts or free starter credits
* Partner-funded daily, weekly, monthly, or one-time allowances
* Custom per-tier discounts
* Partner settlement for sponsored usage

These options are not automatically available just because Partner Auth is enabled. Treat them as request-access features: describe the desired user plans, allowance amounts, discount rates, expected volume, and settlement model to NanoGPT before launch.

Allowance rules are modeled for partner-funded usage:

* one-time signup allowance
* weekly allowance
* monthly allowance

Allowance settlement is not an active production payment source unless NanoGPT explicitly enables it for your integration.

## Error Handling

Common responses:

| Status | Meaning |
| - | - |
| `401` | Missing, invalid, expired, replayed, or unauthorized partner JWT, including a JWT missing the required scope |
| `402` | Linked user needs balance before the request can run |
| `403` | Reading another user's usage with `subject` without the `usage:read:any` scope |
| `429` | Too many requests or too many auth failures |
| `500` | NanoGPT could not complete the server-side operation |

Retry only when the error is transient, such as `429` or `500`.

## Security Checklist

* Sign JWTs only on your backend.
* Keep private keys in your secret manager.
* Use short-lived JWTs, max 5 minutes.
* Use a unique `jti` per request token.
* Use opaque stable user IDs as `sub`.
* Never put PII in `sub`.
* Request only the scopes needed for the operation.
* Do not expose `usage:read:any` or `deposit:create` from browser code.
* Rotate keys periodically and revoke old keys after rollout.

## Minimal Backend Flow

1. User opens your AI feature.
2. Your backend signs a JWT with `sub = your user id` and the needed scope.
3. Your backend calls NanoGPT with `Authorization: Bearer <jwt>`.
4. NanoGPT verifies the JWT and maps the user to a linked NanoGPT account.
5. NanoGPT runs the request, checks balance, applies configured partner discount, and records usage.
6. Your product renders the result to the user.


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