Authentication
Connect the SDK with an API key or OAuth access token.
Use an API key for server-side scripts and services, or an OAuth access token for an authorized integration. Choose one authentication method per client.
API Key
Create an API key in the Namera dashboard and select the session grants and explicit workspace management permissions your application needs. Copy the key when it is shown and save it in your environment:
NAMERA_API_KEY=your_api_keyPass it to the client:
import { NameraClient } from "@namera-ai/sdk";
const namera = new NameraClient({
apiKey: process.env.NAMERA_API_KEY!,
});For a local script, load .env when running it:
node --env-file=.env index.tsKeep your API key private
Keep API keys on your server and .env out of Git. Never include a key in browser code.
An execution-only API key accesses accounts through its session grants. Explicit
wallet:read and session-key:read permissions allow workspace-wide management
reads. Creation, installation, removal, and revocation need their own
management permissions.
A key does not inherit its creator’s complete role.
OAuth Access Token
If your integration already has a Namera OAuth access token, pass it as
accessToken:
import { NameraClient } from "@namera-ai/sdk";
const namera = new NameraClient({
accessToken: process.env.NAMERA_ACCESS_TOKEN!,
});Use the access token, not the refresh token. The client uses the scopes and session-key grants approved for that authorization.
Refreshable Tokens
For a long-running integration, use getAccessToken. The SDK calls it before
each request so your application can supply a current token.
import { NameraClient } from "@namera-ai/sdk";
export async function listAccounts(getAccessToken: () => Promise<string>) {
const namera = new NameraClient({ getAccessToken });
const wallets = await namera.wallets.list();
if (!wallets.success) throw new Error(wallets.error.message);
return wallets.data;
}Pass your application's token-loading function to listAccounts. That function
should refresh an expired token before returning it. The SDK does not run the
OAuth flow or refresh tokens for you.
Check Your Connection
With either client, inspect the authenticated identity and its grants:
const actor = await namera.auth.currentActor();
if (!actor.success) throw new Error(actor.error.message);
console.log(actor.data);If authentication fails, check that the credential has not expired or been revoked. If an account is missing, check its grants or workspace read permissions.
To rotate an API key, create a replacement with the required grants, management permissions, and passkey origins, update your application, then revoke the old key in the dashboard.