> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nova.galaxa.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer Platform & API Keys

> Programmatic access to Galaxa Nova AI with scoped API keys, SHA-256 storage, and enterprise security.

# Developer Platform & API Keys

Galaxa Nova AI provides an enterprise-grade REST API enabling merchants and developers to programmatically trigger WhatsApp templates, ingest external CRM contacts, and query real-time revenue attribution metrics.

Whether you are synchronizing custom warehouse ERPs, dispatching bespoke notifications, or building custom reporting dashboards, the Nova Developer Platform provides secure, low-latency API access.

***

## Security Architecture

Nova follows strict cryptographic and architectural standards for developer credentials:

```mermaid theme={null}
flowchart TD
    A["Merchant Admin Requests New API Key"] --> B["Server Generates nova_live_<48-hex> Token"]
    B --> C["Server Computes SHA-256 Hash"]
    C --> D["Store Hash in Deno KV Index\n['api_key_lookup', keyHash]"]
    B --> E["Return Raw Secret Once to Merchant in Modal"]
    E --> F["Client Stores Token in Secret Manager"]
    D -.->|Raw Secret Never Stored on Disk| G["Zero-Knowledge Hash Verification on Requests"]
```

### 1. One-Time Token Generation

When an administrator generates a new key in **Settings -> Developer API & Webhooks**, Nova generates a cryptographically random token with the prefix `nova_live_` followed by 48 hexadecimal characters.

* The raw secret token is displayed **only once** in the dashboard modal.
* The server stores only the irreversible **SHA-256 hash** of the key.
* Even in the event of an infrastructure snapshot or database inspection, plaintext API tokens cannot be recovered or compromised.

### 2. Granular Scopes

API keys are scoped with least-privilege permissions:

| Scope | Description | Permitted Endpoints |
| :- | :- | :- |
| `whatsapp:send` | Dispatch outbound WhatsApp notification templates and alerts | `POST /api/v1/whatsapp/send` |
| `contacts:write` | Upsert customer profiles, phone numbers, and external CRM tags | `POST /api/v1/contacts/upsert` |
| `analytics:read` | Query real-time GMV attribution and conversion metrics | `GET /api/v1/analytics/attribution` |

### 3. Role-Based Administration (RBAC)

Only team members with the **Admin** role can create, view, or revoke Developer API keys:

* Requests from `analyst` or `support` roles to create or delete keys return an immediate `403 Forbidden`.
* All API key generation and revocation events are logged in the organization audit trail.

***

## Authentication

All requests to Nova's Developer API must include your secret token in the `Authorization` header as a Bearer token:

```http theme={null}
Authorization: Bearer nova_live_9f83a4c281e05d7b3a9482f102c9381e4b82d7c01a93e84f
Content-Type: application/json
```

Requests sent without an Authorization header or with an invalid/revoked key return `401 Unauthorized`:

```json theme={null}
{
  "error": "Unauthorized: Invalid or revoked API key"
}
```

Requests that present a valid API key lacking the required scope for the specific endpoint return `403 Forbidden`:

```json theme={null}
{
  "error": "Forbidden: Insufficient API key scope. Required: whatsapp:send"
}
```

***

## Managing Keys in the Dashboard

1. Navigate to the **[Nova Dashboard](https://nova.galaxa.in/dashboard.html)**.
2. Select **Settings** in the left sidebar and scroll to the **Developer API & Webhooks** card.
3. Click **Generate New Key**.
4. Enter a descriptive key name (e.g. `ERP Sync Production` or `Warehouse Webhook`).
5. Check the required permission scopes (`whatsapp:send`, `contacts:write`, `analytics:read`).
6. Click **Generate Key**.
7. Copy the revealed secret key immediately and store it securely in your application's environment configuration.

> [!WARNING]
>
> Once you close the key creation modal, the raw secret token cannot be viewed again. If a key is lost, revoke it and create a new key.

***

## Rate Limits & Quotas

To ensure high availability across all merchants:

* **Standard Tier:** 60 requests per minute per organization across all public v1 endpoints.
* **Burst Limit:** Up to 100 requests per minute for temporary traffic spikes.
* When rate limits are exceeded, the API returns HTTP status code `429 Too Many Requests` with a `Retry-After` header.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.