Authentication

API keys, the scopes they carry, how to send them and how to keep them safe.

On this page

API keys

An API key is a 64-character secret issued in the developer console. NexG stores only a SHA-256 hash of it, so the key is shown once, when it is issued, and cannot be shown again. The console identifies a key by its first eight characters.

A key is not tied to a person's login. It keeps working when the person who issued it signs out, which is what lets a server use it.

Sending a key

Send the key in the X-Api-Key header, or as a bearer token in Authorization. Use one or the other: a request with both is refused with 400 invalid_request, as is an Authorization header that is not Bearer.

curl https://api.nexgapp.com/v1/catalog/merchants \
  -H "X-Api-Key: $NEXG_API_KEY"

Scopes

A key carries one or more scopes, and each endpoint needs one of them.

Scope	Lets a key	Who can have it
`public_read`	Read merchants, catalogues, zones, experiences and services.	Anyone with a NexG account.
`merchant_read`	Read the orders of the one merchant the key is bound to.	The merchant’s owner, or NexG merchant operations.
`merchant_write`	Book services for that merchant, when booking ships. No endpoint uses it yet.	Not issued by the console yet.
`internal_read`, `internal_write`	NexG’s own systems.	NexG staff, issued by a global administrator.

Merchant keys

A key with merchant_read is bound to exactly one merchant when it is issued. The key, never the request, decides the merchant: no endpoint takes a merchant id from you, so a key cannot read another merchant's records by guessing an id.

A merchant key works only while that merchant may operate on NexG. While the merchant is paused, suspended or delisted, or while its application is waiting for approval, its keys are refused, and they work again once it may operate.

Requests without a key

Public endpoints answer without a key. Keyless requests share one anonymous rate limit of 120 tokens a minute across all callers (or 60 a minute for each address, where NexG identifies callers by IP at its edge), so a busy moment elsewhere can slow you down. Use a key for anything you run in production.

When a key is refused

An unknown, revoked or expired key, or a merchant key while its merchant cannot operate, all get the same answer, on purpose: telling them apart would tell a stranger which keys exist.

Response

HTTP/1.1 401 Unauthorized
Cache-Control: no-store
X-Request-Id: 3d0c8f8e-9a51-4f0e-8a77-1c5b2f6d9e40

{
  "ok": false,
  "error": { "code": "not_found", "message": "That API key is not valid." },
  "meta": { "api_version": "v1" }
}

A valid key without the scope an endpoint needs gets 403 with code not_found. See Errors for the full list.

Keeping keys safe

Call the API from your server. Never put a key in browser code, a mobile app or a URL.
Keep it in your host's secret store or environment, and never in a variable your framework exposes to the browser (in Next.js, anything named NEXT_PUBLIC_…).
Never commit a key, paste it into a ticket or chat, or log it.
Give each system its own key with only the scopes it needs.

To replace a key, issue a new one, deploy it, then have the old one revoked. The database already supports revoking a key; until the console can list and revoke keys, ask NexG to revoke it for you.

Listing and revoking keys in the console

The console issues keys today. Seeing your keys and revoking them there is coming soon.

OAuth

NexG has storage for OAuth clients, but no authorization or token endpoints. Use an API key. OAuth will be announced in the changelog if it ships.