Partner Auth - NanoGPT API Documentation

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.

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.

How It Works

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:

Authorization: Bearer <partner-signed JWT>

JWT header:

{
  "alg": "ES256",
  "kid": "example-2026-04"
}

JWT claims:

{
  "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:

{
  "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.

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:

request:create

The request is charged to the linked NanoGPT account for the JWT sub. See also: Chat Completion, Image Generation, and Video Generation.

Check User Balance

curl -X POST "https://nano-gpt.com/api/check-balance" \
  -H "Authorization: Bearer $PARTNER_JWT"

The JWT must include:

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. See Check User Balance.
Crypto invoice or swap deposits: call POST /api/transaction/create/{ticker} for supported tickers such as btc, btc-ln, ltc, ltc-mweb, xmr, doge, dash, zec, bch, kas, ton, near, egld, vvv, zano, or fusd.
Card deposits where enabled for the partner integration.

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:

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:

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.

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:

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:

session:web

NanoGPT returns:

{
  "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:

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

The JWT must include:

usage:read

Backend service usage lookup for a specific user:

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:

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
`402`	Linked user needs balance before the request can run
`403`	JWT is valid but missing the required 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

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

​Overview

​How It Works

​What NanoGPT Configures

​JWT Requirements

​Scopes

​Send AI Requests

​Check User Balance

​Initiate A Top-Up

​Browser SSO

​Read User Usage

​Funding Options

​Request-Access Funding Features

​Error Handling

​Security Checklist

​Minimal Backend Flow

Overview

How It Works

What NanoGPT Configures

JWT Requirements

Scopes

Send AI Requests

Check User Balance

Initiate A Top-Up

Browser SSO

Read User Usage

Funding Options

Request-Access Funding Features

Error Handling

Security Checklist

Minimal Backend Flow