Authorization

The Nexus API supports multiple authentication methods. You can either use an API key (recommended for most applications) or a Web3 wallet (for token-gated access and on-chain identity).

---

API Key Authentication

API keys are the simplest way to authenticate with Nexus.

1. Go to the Nexus web app.
2. Navigate to Configuration → API Keys.
3. Create a new API key for your application.
   • API key secrets are shown only once at creation. Store them securely.
4. Use the key in the Authorization header when making requests.

Example header:

Key	Value
Authorization	Bearer API_KEY

---

Revoking an API Key (Kill Switch)

For additional security, Nexus API keys can revoke themselves.
This allows you to build a kill switch directly into your applications. For example, if your app detects suspicious activity during execution.

To revoke an API key, call:

POST /apikeys/revoke/{api_key_id}

• api_key_id is the identifier of the key (shown in the web UI when you click on an API key).
• ⚠️ This is not the same as the API key secret used for authentication.

Example header:

Key	Value
Authorization	Bearer API_KEY_SECRET

Example request:

POST /apikeys/revoke/12345
Authorization: Bearer nai_p_xxx...

Example response:

{
  "status": "ok",
  "message": "API key revoked successfully."
}

After revocation, the key will no longer work for authentication. You can always generate a new key in the Nexus web app.

---

Web3 Wallet Authentication

Web3 authentication uses a wallet-based challenge/response flow. Nexus verifies a signed message and issues a JWT access token that you can use for subsequent requests.

Flow

1. Request a message to sign using your wallet address.
2. Sign the message with your wallet's private key.
3. Send the signature to the server for verification.
4. Receive a JWT access token.
5. Use the JWT in the Authorization header for all secured endpoints.

---

Endpoints

1. Request a challenge message

GET /auth/challenge?wallet={wallet_address}

Response:

{
  "status": "ok",
  "data": {
    "nonce": "Sign this message to login: f50c4b44b7dcd2caac364579653ab4f0"
  }
}

2. Verify the signature

POST /auth/verify

Payload:

{
  "wallet": "0x23..",
  "signature": "0x..."
}

Response:

{
  "status": "ok",
  "data": {
    "access_token": "eyJh...",
    "nexus_uuid": "..."
  }
}

---

Using the JWT

Once issued, include the JWT in the Authorization header:

Key	Value
Authorization	Bearer eyJh...

---

Example Code

Below are minimal examples in Python and JavaScript to illustrate the full wallet flow:

Python

import requests
from eth_account import Account

BASE_URL = "https://api.nexus.nukl.ai"

wallet = "0xYourWalletAddress"
private_key = "0xYourPrivateKey"

# Step 1: Get challenge
resp = requests.get(f"{BASE_URL}/auth/challenge?wallet={wallet}").json()
message = resp['data']['nonce']

# Step 2: Sign message
signed_message = Account.sign_message(
    Account.signable_message.TextMessage(message),
    private_key
).signature.hex()

# Step 3: Verify
verify_resp = requests.post(f"{BASE_URL}/auth/verify", json={
    "wallet": wallet,
    "signature": signed_message
}).json()

access_token = verify_resp['data']['access_token']

headers = {"Authorization": f"Bearer {access_token}"}
# Now use `headers` in secured requests.

JavaScript

const axios = require('axios');
const { ethers } = require('ethers');

const BASE_URL = 'https://api.nexus.nukl.ai';

const wallet = new ethers.Wallet('0xYourPrivateKey');

// Step 1: Get challenge
const { data: challengeResp } = await axios.get(`${BASE_URL}/auth/challenge?wallet=${wallet.address}`);
const message = challengeResp.data.nonce;

// Step 2: Sign message
const signature = await wallet.signMessage(message);

// Step 3: Verify
const { data: verifyResp } = await axios.post(`${BASE_URL}/auth/verify`, {
    wallet: wallet.address,
    signature: signature
});

const accessToken = verifyResp.data.access_token;

const headers = { Authorization: `Bearer ${accessToken}` };
// Now use `headers` in secured requests.

---

You're now authorized to call Nexus secured endpoints, like /chat/session/new, with either an API key or JWT from wallet auth.