Authentication

Gero Nexus has two credential types. Pick the one that matches how you’re calling the API:

API key (recommended)

For servers, scripts, and integrations

Sent in the X-Api-Key header
Long-lived — does not expire hourly
Created in the dashboard; keys start with nxs_

Session token (JWT)

For the web dashboard and mobile apps

Sent as Authorization: Bearer <token>
Short-lived (1 hour), paired with a refresh token
Issued by /api/auth/login or /api/auth/device

These are not interchangeable. An API key (nxs_...) goes in the X-Api-Key header — putting it in Authorization: Bearer returns 401 Unauthorized. Authorization: Bearer is only for JWT session tokens.

API key authentication (recommended)

For server-to-server access, scripts, and most integrations, use an API key. Unlike a session token, it doesn’t expire every hour.

1. Create a key

Sign in to the dashboard, create an API key, and copy it. Keys are shown once and look like nxs_uYc.... Each API key is scoped to one chain and one network, chosen at creation time (see Key scope below).

2. Send it in the `X-Api-Key` header

curl -X GET "https://nexus.gerowallet.io/api/blocks?page=1&pageSize=100" \
  -H "X-Api-Key: nxs_your_api_key_here"

const response = await fetch('https://nexus.gerowallet.io/api/blocks?page=1&pageSize=100', {
  headers: { 'X-Api-Key': 'nxs_your_api_key_here' }
});

const blocks = await response.json();

import requests

response = requests.get(
    'https://nexus.gerowallet.io/api/blocks',
    params={'page': 1, 'pageSize': 100},
    headers={'X-Api-Key': 'nxs_your_api_key_here'}
)

blocks = response.json()

That’s the whole protocol for API-key access: HTTPS plus an X-Api-Key header. No token exchange, no refresh loop.

Most endpoints accept a network query parameter. Supported values:

Chain	Networks
Cardano	`CARDANO_MAINNET`, `CARDANO_PREPROD`, `CARDANO_PREVIEW`
Midnight	`MIDNIGHT_MAINNET`, `MIDNIGHT_PREPROD`, `MIDNIGHT_STAGENET`
Apex	`APEX_PRIME_MAINNET`, `APEX_VECTOR_MAINNET`, `APEX_VECTOR_TESTNET`
Bitcoin	`BITCOIN_MAINNET`, `BITCOIN_TESTNET4`

Every value names a chain and a network together, and that pair is exactly the scope of one API key.

Key scope: one chain, one network

Each API key is bound to a single value from the table above at creation time. That value fixes both the chain and the network, so:

A CARDANO_MAINNET key cannot query CARDANO_PREPROD or CARDANO_PREVIEW.
A CARDANO_MAINNET key cannot query Bitcoin or Midnight at all.
To call more than one chain, or more than one network on the same chain, create one key per chain and network under the same account.

Passing a network query parameter that does not match the key’s own network returns HTTP 400 Network Mismatch:

{
  "timestamp": "2026-06-23T15:30:00.123",
  "status": 400,
  "error": "Network Mismatch",
  "message": "API key is bound to CARDANO_MAINNET but request specified CARDANO_PREPROD",
  "path": "/api/blocks/latest",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Omit the network parameter and the request runs against the key’s own network, which is usually what you want. What stays uniform across chains is the integration surface, not the credential: one account, one base URL, one X-Api-Key header, and one docs site. You integrate once and add chains without re-architecting.

Network scope and capability are separate gates. Market data, wallet analytics, transaction building, MCP, and IPFS are paid add-ons; their endpoints return HTTP 402 on a key whose plan does not carry the matching add-on, even when the chain and network match.

Blockfrost SDKs and the project ID header

Nexus also serves a Blockfrost-compatible surface at https://nexus.gerowallet.io/api/v0, and every Blockfrost SDK sends its credential as a project_id header. On that surface, project_id is accepted and is exactly equivalent to X-Api-Key: it carries the same nxs_ key, on the same plan, with the same quota and rate limits.

curl -X GET "https://nexus.gerowallet.io/api/v0/blocks/latest" \
  -H "project_id: nxs_your_api_key_here"

Two rules:

project_id works only on /api/v0. Native endpoints under /api/... continue to require the X-Api-Key header, and a project_id header there is ignored.
If a request sends both, the explicit X-Api-Key wins.

Nothing changes for native integrations. project_id exists so that an unmodified Blockfrost SDK authenticates without code changes. See Blockfrost compatibility.

Session authentication (browser & mobile apps)

The web dashboard and mobile apps authenticate users with short-lived JWT session tokens instead of an API key. You only need this if you’re building a user-facing app that logs people in — for server-to-server API calls, use an API key (above).

1. Get an access token

User Login
Device Auth

curl -X POST "https://nexus.gerowallet.io/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJIUzUxMiJ9...",
  "refreshToken": "eyJhbGciOiJIUzUxMiJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600000,
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "your-email@example.com",
    "roles": ["USER"]
  }
}

curl -X POST "https://nexus.gerowallet.io/api/auth/device" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "unique-device-identifier",
    "deviceName": "My iPhone",
    "platform": "IOS"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJIUzUxMiJ9...",
  "refreshToken": "eyJhbGciOiJIUzUxMiJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600000
}

2. Use the Token

Include the access token in the Authorization header for all API requests:

curl -X GET "https://nexus.gerowallet.io/api/blocks/latest" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..."

User Authentication

For web applications and services that require user accounts.

Register a New Account

curl -X POST "https://nexus.gerowallet.io/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123",
    "username": "myusername"
  }'

const response = await fetch('https://nexus.gerowallet.io/api/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'securePassword123',
    username: 'myusername'
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://nexus.gerowallet.io/api/auth/register',
    json={
        'email': 'user@example.com',
        'password': 'securePassword123',
        'username': 'myusername'
    }
)

data = response.json()

curl -X POST "https://nexus.gerowallet.io/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123"
  }'

const response = await fetch('https://nexus.gerowallet.io/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'securePassword123'
  })
});

const { accessToken, refreshToken } = await response.json();

// Store tokens securely
localStorage.setItem('accessToken', accessToken);
localStorage.setItem('refreshToken', refreshToken);

import requests

response = requests.post(
    'https://nexus.gerowallet.io/api/auth/login',
    json={
        'email': 'user@example.com',
        'password': 'securePassword123'
    }
)

tokens = response.json()
access_token = tokens['accessToken']
refresh_token = tokens['refreshToken']

Logout

Invalidates the current session and refresh token:

curl -X POST "https://nexus.gerowallet.io/api/auth/logout" \
  -H "Authorization: Bearer your-access-token"

Device Authentication

For mobile applications that don’t require user credentials. Devices are automatically registered on first use.

Authenticate Device

curl -X POST "https://nexus.gerowallet.io/api/auth/device" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "550e8400-e29b-41d4-a716-446655440000",
    "deviceName": "iPhone 15 Pro",
    "platform": "IOS"
  }'

// Generate or retrieve persistent device ID
const deviceId = await getDeviceId(); // Your device ID logic

const response = await fetch('https://nexus.gerowallet.io/api/auth/device', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deviceId: deviceId,
    deviceName: 'My App',
    platform: 'IOS' // or 'ANDROID', 'WEB'
  })
});

const { accessToken, refreshToken } = await response.json();

struct DeviceAuthRequest: Codable {
    let deviceId: String
    let deviceName: String
    let platform: String
}

func authenticateDevice() async throws -> TokenResponse {
    let deviceId = UIDevice.current.identifierForVendor?.uuidString ?? UUID().uuidString

    let request = DeviceAuthRequest(
        deviceId: deviceId,
        deviceName: UIDevice.current.name,
        platform: "IOS"
    )

    var urlRequest = URLRequest(url: URL(string: "https://nexus.gerowallet.io/api/auth/device")!)
    urlRequest.httpMethod = "POST"
    urlRequest.setValue("application/json", forHTTPHeaderField: "Content-Type")
    urlRequest.httpBody = try JSONEncoder().encode(request)

    let (data, _) = try await URLSession.shared.data(for: urlRequest)
    return try JSONDecoder().decode(TokenResponse.self, from: data)
}

data class DeviceAuthRequest(
    val deviceId: String,
    val deviceName: String,
    val platform: String
)

suspend fun authenticateDevice(): TokenResponse {
    val deviceId = Settings.Secure.getString(
        context.contentResolver,
        Settings.Secure.ANDROID_ID
    )

    val request = DeviceAuthRequest(
        deviceId = deviceId,
        deviceName = Build.MODEL,
        platform = "ANDROID"
    )

    return apiService.authenticateDevice(request)
}

Platform Values

Platform	Description
`IOS`	iOS devices (iPhone, iPad)
`ANDROID`	Android devices
`WEB`	Web browsers

Token Management

Token Structure

When you authenticate, you receive:

Field	Description
`accessToken`	Short-lived token for API requests (1 hour)
`refreshToken`	Long-lived token to get new access tokens (7 days)
`tokenType`	Always `Bearer`
`expiresIn`	Access token lifetime in milliseconds

Refresh Tokens

Before your access token expires, use the refresh token to get a new one:

User Refresh
Device Refresh

curl -X POST "https://nexus.gerowallet.io/api/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "your-refresh-token"
  }'

curl -X POST "https://nexus.gerowallet.io/api/auth/device/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "your-refresh-token"
  }'

Refresh tokens are single-use. Each refresh returns a new refresh token.

Making session-authenticated requests

Once you have a session access token, include it in the Authorization header. (For server-to-server access, use an API key in the X-Api-Key header instead.)

curl -X GET "https://nexus.gerowallet.io/api/blocks/latest" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..."

const response = await fetch('https://nexus.gerowallet.io/api/blocks/latest', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const data = await response.json();

import requests

response = requests.get(
    'https://nexus.gerowallet.io/api/blocks/latest',
    headers={
        'Authorization': f'Bearer {access_token}'
    }
)

data = response.json()

Example: Secure API Client

Here’s a production-ready example with automatic token refresh:

class GeroNexusClient {
  constructor() {
    this.baseUrl = 'https://nexus.gerowallet.io';
    this.accessToken = null;
    this.refreshToken = null;
    this.tokenExpiry = null;
  }

  async authenticate(email, password) {
    const response = await fetch(`${this.baseUrl}/api/auth/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, password })
    });

    const data = await response.json();
    this.setTokens(data);
    return data;
  }

  async authenticateDevice(deviceId, deviceName, platform) {
    const response = await fetch(`${this.baseUrl}/api/auth/device`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ deviceId, deviceName, platform })
    });

    const data = await response.json();
    this.setTokens(data);
    return data;
  }

  setTokens(data) {
    this.accessToken = data.accessToken;
    this.refreshToken = data.refreshToken;
    this.tokenExpiry = Date.now() + data.expiresIn - 60000; // 1 min buffer
  }

  async ensureValidToken() {
    if (!this.tokenExpiry || Date.now() >= this.tokenExpiry) {
      await this.refreshAccessToken();
    }
  }

  async refreshAccessToken() {
    const response = await fetch(`${this.baseUrl}/api/auth/refresh`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ refreshToken: this.refreshToken })
    });

    const data = await response.json();
    this.setTokens(data);
  }

  async request(endpoint, options = {}) {
    await this.ensureValidToken();

    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json',
        ...options.headers
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status}`);
    }

    return response.json();
  }

  // Convenience methods
  getLatestBlock() {
    return this.request('/api/blocks/latest');
  }

  getTransaction(hash) {
    return this.request(`/api/transactions/${hash}`);
  }
}

// Usage
const client = new GeroNexusClient();
await client.authenticate('user@example.com', 'password');
const block = await client.getLatestBlock();

import requests
import time
from typing import Optional

class GeroNexusClient:
    """Secure API client with automatic token refresh"""

    def __init__(self):
        self.base_url = 'https://nexus.gerowallet.io'
        self.access_token: Optional[str] = None
        self.refresh_token: Optional[str] = None
        self.token_expiry: Optional[float] = None
        self.session = requests.Session()

    def authenticate(self, email: str, password: str):
        """Authenticate with email and password"""
        response = self.session.post(
            f'{self.base_url}/api/auth/login',
            json={'email': email, 'password': password}
        )
        response.raise_for_status()
        self._set_tokens(response.json())

    def authenticate_device(self, device_id: str, device_name: str, platform: str):
        """Authenticate with device credentials"""
        response = self.session.post(
            f'{self.base_url}/api/auth/device',
            json={
                'deviceId': device_id,
                'deviceName': device_name,
                'platform': platform
            }
        )
        response.raise_for_status()
        self._set_tokens(response.json())

    def _set_tokens(self, data: dict):
        self.access_token = data['accessToken']
        self.refresh_token = data['refreshToken']
        # Set expiry with 1 minute buffer
        self.token_expiry = time.time() + (data['expiresIn'] / 1000) - 60

    def _ensure_valid_token(self):
        if not self.token_expiry or time.time() >= self.token_expiry:
            self._refresh_access_token()

    def _refresh_access_token(self):
        response = self.session.post(
            f'{self.base_url}/api/auth/refresh',
            json={'refreshToken': self.refresh_token}
        )
        response.raise_for_status()
        self._set_tokens(response.json())

    def request(self, endpoint: str, method: str = 'GET', **kwargs):
        """Make authenticated API request"""
        self._ensure_valid_token()

        headers = {
            'Authorization': f'Bearer {self.access_token}',
            'Content-Type': 'application/json'
        }

        response = self.session.request(
            method,
            f'{self.base_url}{endpoint}',
            headers=headers,
            **kwargs
        )
        response.raise_for_status()
        return response.json()

    # Convenience methods
    def get_latest_block(self):
        return self.request('/api/blocks/latest')

    def get_transaction(self, tx_hash: str):
        return self.request(f'/api/transactions/{tx_hash}')


# Usage
if __name__ == '__main__':
    client = GeroNexusClient()
    client.authenticate('user@example.com', 'password')
    block = client.get_latest_block()
    print(block)

Error Handling

Common Authentication Errors

error

Invalid or expired token

{
  "error": "Unauthorized",
  "message": "Invalid or expired access token"
}

Solution: Refresh your access token or re-authenticate.

error

Wrong email or password

{
  "error": "Invalid email or password"
}

Solution: Check your credentials and try again.

error

Insufficient permissions

{
  "error": "Forbidden",
  "message": "You don't have permission to access this resource"
}

Solution: Check if your account has the required role/permissions.

Best Practices

Secure Token Storage

Web Applications:

Store tokens in httpOnly cookies when possible
Use localStorage only if cookies aren’t an option
Never store tokens in sessionStorage for persistent auth

Mobile Applications:

Use iOS Keychain or Android Keystore
Never store tokens in plain text
Clear tokens on logout and app uninstall

Server Applications:

Store tokens in secure environment variables
Use secret management services (AWS Secrets Manager, HashiCorp Vault)
Never log tokens

Token Refresh Strategy

Refresh tokens proactively before expiry (60 seconds buffer)
Implement retry logic for failed refreshes
Handle refresh token expiry by re-authenticating
Queue requests while refreshing to avoid race conditions

Device ID Generation

iOS:

let deviceId = UIDevice.current.identifierForVendor?.uuidString

Android:

val deviceId = Settings.Secure.getString(
    context.contentResolver,
    Settings.Secure.ANDROID_ID
)

Web:

// Generate once and store
const deviceId = localStorage.getItem('deviceId')
  || (localStorage.setItem('deviceId', crypto.randomUUID()),
      localStorage.getItem('deviceId'));

Error Recovery

Handle token errors gracefully:

401 with valid refresh token → Refresh and retry
401 with expired refresh token → Re-authenticate
Network error → Retry with exponential backoff
403 → Check user permissions, may need different credentials

Next Steps

Quick Start

Make your first authenticated API call

Rate Limits

Understand rate limiting and quotas

Error Handling

Learn how to handle API errors

API Reference

Explore all available endpoints

Security Question? Contact our security team at security@gerowallet.io

Getting Started

Migrations

Core Concepts

Add-ons & Streaming

API Reference

API key (recommended)

Session token (JWT)

API key authentication (recommended)

1. Create a key

2. Send it in the `X-Api-Key` header

Key scope: one chain, one network

Blockfrost SDKs and the project ID header

Session authentication (browser & mobile apps)

1. Get an access token

2. Use the Token

User Authentication

Register a New Account

Logout

Device Authentication

Authenticate Device

Platform Values

Token Management

Token Structure

Refresh Tokens

Making session-authenticated requests

Example: Secure API Client

Error Handling

Common Authentication Errors

Best Practices

Next Steps

Quick Start

Rate Limits

Error Handling

API Reference

API key (recommended)

Session token (JWT)

​API key authentication (recommended)

​1. Create a key

​2. Send it in the X-Api-Key header

​Key scope: one chain, one network

​Blockfrost SDKs and the project ID header

​Session authentication (browser & mobile apps)

​1. Get an access token

​2. Use the Token

​User Authentication

​Register a New Account

​Login

​Logout

​Device Authentication

​Authenticate Device

​Platform Values

​Token Management

​Token Structure

​Refresh Tokens

​Making session-authenticated requests

​Example: Secure API Client

​Error Handling

​Common Authentication Errors

​Best Practices

​Next Steps

Quick Start

Rate Limits

Error Handling

API Reference

API key authentication (recommended)

1. Create a key

2. Send it in the `X-Api-Key` header

Key scope: one chain, one network

Blockfrost SDKs and the project ID header

Session authentication (browser & mobile apps)

1. Get an access token

2. Use the Token

User Authentication

Register a New Account

Login

Logout

Device Authentication

Authenticate Device

Platform Values

Token Management

Token Structure

Refresh Tokens

Making session-authenticated requests

Example: Secure API Client

Error Handling

Common Authentication Errors

Best Practices

Next Steps