Skip to main content
API requests use the X-API-Key header as the canonical credential shape. The TypeScript SDK sends that header when you pass apiKey to ApiClient. Hosted MCP uses the same API key as Authorization: Bearer cns_pk_... because remote MCP clients commonly support bearer-style auth. This is an API-key compatibility alias only. OAuth bearer tokens, JWT bearer tokens, and non-API-key bearer values are not supported. For testnet access, you can self-onboard at developers.shodai.network/portal and create an API key. You can use that key in your own integration or try it immediately in the Agreements API Playground. Production API keys are provisioned by your API operator, who hands the plaintext key to the recipient once.
Store the plaintext key when it is issued. The API stores only the hashed key afterward.

​
Send the API key

For Quickstart with TypeScript SDK, pass the key when constructing the client: 
import { ApiClient } from '@cns-labs/agreements-api-client';

const client = new ApiClient({
  environment: 'testnet',
  apiKey: process.env.API_KEY,
});
For Quickstart with MCP, configure the hosted server with a bearer-style API key: 
Authorization: Bearer cns_pk_...
For raw HTTP debugging, send the same value as X-API-Key: 
curl -sS "$BASE_URL/v0/agreements" \
  -H "X-API-Key: $API_KEY"
For clients that cannot set custom API-key headers, the bearer-style alias also works: 
curl -sS "$BASE_URL/v0/agreements" \
  -H "Authorization: Bearer $API_KEY"

​
Scopes and entitlements

API access is controlled by entitlements on the API principal. Testnet keys created through the Developer Portal are intended to include the default agreement read and write scopes. Manually provisioned principals should be checked for the scopes your integration needs.
ScopeUse
agreements.readRead agreement records, state, and input history.
agreements.writeValidate, deploy, and submit agreement inputs.
agreements.*Wildcard access for agreement scopes.
*Broad wildcard access. Use only for internal testing.
Entitlement modes are:
ModeResult
free_allowlistAllows the scoped operation.
blockedReturns 403 Forbidden for the scoped operation.
paid_requiredReturns 402 Payment Required; per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.
If the principal has no active entitlement for the requested scope, the API returns 403 Forbidden.

​
Common authentication failures

StatusMeaningWhat to check
401Missing, invalid, revoked, disabled, or unsupported API credential.Confirm X-API-Key is present with the current plaintext key, or use Authorization: Bearer cns_pk_... only as an API-key alias.
402The authenticated API principal has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented.Treat this as an entitlement/operator issue and ask your API operator to review the requested scope.
403The key is authenticated but not allowed for this scope or resource.Confirm the principal has agreements.read, agreements.write, agreements.*, or * as appropriate, and that no blocked entitlement applies.

​
Header casing

API auth header names are case-insensitive at the HTTP layer, but examples use X-API-Key consistently.