Documentation — Nexus API

The Nexus API uses API keys to authenticate requests. You can view and manage your API keys in the Developer Dashboard. Your API keys carry many privileges, so be sure to keep them secure!

Keep your keys safe

Do not share your API keys in publicly accessible areas such as GitHub, client-side code, or public documentation.

API Keys

All API requests must include your API key in the Authorization header. API keys are prefixed with nx_live_ for production and nx_test_ for sandbox environments.

bash

# Include your API key in the Authorization header
curl https://api.nexus.dev/v1/users \
  -H "Authorization: Bearer nx_live_abc123..." \
  -H "Content-Type: application/json"

Key Types

Nexus provides two types of API keys for different use cases:

Publishable keys — Can be safely used in client-side code. Limited to read-only operations.
Secret keys — Must only be used server-side. Full access to all API operations.

OAuth 2.0

For applications that need to access user data on behalf of other Nexus users, we support OAuth 2.0. This allows your users to authorize your application without sharing their credentials.

Use our OAuth libraries

We provide official OAuth libraries for Node.js, Python, and Ruby that handle the complexity of token management for you.

Authorization Flow

The OAuth flow involves redirecting users to Nexus, where they approve your app's access request. After approval, they're redirected back to your app with an authorization code that you exchange for an access token.

javascript

import { NexusOAuth } from '@nexus/oauth';

const oauth = new NexusOAuth({
  clientId: process.env.NEXUS_CLIENT_ID,
  clientSecret: process.env.NEXUS_CLIENT_SECRET,
  redirectUri: 'https://yourapp.com/callback'
});

// Generate authorization URL
const authUrl = oauth.getAuthorizationUrl({
  scope: ['read:users', 'write:payments'],
  state: generateRandomState()
});

// Exchange code for tokens
const tokens = await oauth.exchangeCode(code);

JWT Tokens

For microservices and server-to-server communication, you can use JWT tokens signed with your API secret. JWTs provide a secure, stateless way to authenticate requests without storing session data.

Token expiration

JWT tokens expire after 1 hour by default. Use refresh tokens to obtain new access tokens without re-authentication.

python

from nexus import Client

client = Client(
    api_key="nx_live_abc123...",
    jwt_secret="your_jwt_secret"
)

# Generate a signed JWT for service authentication
token = client.generate_jwt(
    claims={
        "service": "payment-processor",
        "permissions": ["process_payments"]
    },
    expires_in=3600
)

Frequently Asked Questions

You can rotate API keys from the Developer Dashboard. When you create a new key, the old key remains active for 24 hours to give you time to update your applications. After rotation, be sure to update all services using the old key.

Immediately revoke the compromised key in your Dashboard and generate a new one. Review your API logs for any unauthorized access. Enable IP allowlisting as an additional security measure. Contact [email protected] if you notice any suspicious activity.

We strongly recommend using separate API keys for development, staging, and production environments. This helps isolate issues and prevents accidental production modifications during development. Test keys (nx_test_*) only work with sandbox endpoints.

Available scopes include: read:users, write:users, read:payments, write:payments, read:messages, write:messages, and admin:all. Request only the scopes your application needs. Users can see all requested scopes during authorization.

Access tokens expire after 1 hour. Refresh tokens are valid for 30 days or until revoked. Use the refresh token to obtain new access tokens without requiring users to re-authorize. Store refresh tokens securely on your server.

Authentication endpoints have a rate limit of 100 requests per minute per IP address. Failed authentication attempts are limited to 10 per minute to prevent brute force attacks. Contact us if you need higher limits for legitimate use cases.