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

# Organisation Domains

> Understand the domain patterns used by the Nudj APIs

Every Nudj API endpoint is scoped to your organisation's domain. This page explains the patterns in use and points you at the Admin API endpoints that manage white-label custom domains.

<Note>
  Looking to add a white-label domain for your members? The full admin walkthrough lives at [Custom Domain Setup](/admin-guide/settings/domains).
</Note>

## Domain patterns

Your organisation's API endpoints follow this pattern:

```
https://{your-organization-domain}/api/v2/{api-type}/{endpoint}
```

| Pattern                 | Example                  | When used                                                                      |
| ----------------------- | ------------------------ | ------------------------------------------------------------------------------ |
| Standard Nudj subdomain | `acme-corp.nudj.cx`      | Default for every organisation                                                 |
| Custom subdomain        | `api.yourcompany.com`    | Registered via `POST /domains`                                                 |
| White-label             | `rewards.enterprise.com` | Registered via `POST /domains`, often paired with a member-facing brand domain |

Tokens are tied to the subdomain they were issued for — a token minted for `acme-corp.nudj.cx` cannot be replayed against a different organisation's subdomain. This is enforced by the auth middleware at request time.

## Managing custom domains via the Admin API

The Admin API exposes three endpoints for custom-domain lifecycle:

<CardGroup cols={2}>
  <Card title="GET /domains" icon="list" href="/api-reference/admin/get-domains">
    List every domain registered for your organisation.
  </Card>

  <Card title="POST /domains" icon="plus" href="/api-reference/admin/post-domains">
    Register a new custom domain. Triggers DNS + SSL provisioning.
  </Card>

  <Card title="POST /domains/remove" icon="trash" href="/api-reference/admin/post-domains-remove">
    Retire a domain. Existing tokens scoped to that domain stop being accepted.
  </Card>
</CardGroup>

For the DNS / SSL / verification walkthrough, see the [admin-side guide](/admin-guide/settings/domains) — that covers the UI flow in the admin dashboard that wraps these endpoints.

## Using your domain from code

When building an integration, always use your organisation's actual domain — never a hard-coded dev/staging host.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const API_DOMAIN = process.env.NUDJ_API_DOMAIN; // e.g. 'acme-corp.nudj.cx'
  const API_TOKEN = process.env.NUDJ_API_TOKEN;

  async function fetchAchievements() {
    const response = await fetch(
      `https://${API_DOMAIN}/api/v2/integration/achievements`,
      {
        headers: {
          'Authorization': `Bearer ${API_TOKEN}`,
          'Content-Type': 'application/json'
        }
      }
    );
    return response.json();
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  API_DOMAIN = os.environ['NUDJ_API_DOMAIN']  # e.g. 'acme-corp.nudj.cx'
  API_TOKEN = os.environ['NUDJ_API_TOKEN']

  def fetch_achievements():
      response = requests.get(
          f'https://{API_DOMAIN}/api/v2/integration/achievements',
          headers={
              'Authorization': f'Bearer {API_TOKEN}',
              'Content-Type': 'application/json'
          }
      )
      return response.json()
  ```
</CodeGroup>

## Finding your domain

1. **Check Developer Settings** — [Settings → Organisation → Developer](https://admin.nudj.cx/admin/settings/organisation?tab=developer) lists the active domain for your organisation.
2. **Match your admin URL** — the admin dashboard for your organisation runs on the same subdomain (e.g. admin is served under `{your-subdomain}.nudj.cx`).
3. **Ask your administrator** — they have the full list of registered custom domains and can issue a new one via the Admin API or the admin UI.

## Troubleshooting

<AccordionGroup>
  <Accordion title="404 Not Found">
    * Verify you're hitting your organisation's actual domain — not `nudjdev` or `nudjstaging`.
    * Check the path starts with `/api/v2/` and uses `integration`, `admin`, or `analytics`.
    * Confirm the endpoint exists for the API type you're calling.
  </Accordion>

  <Accordion title="401 Unauthorized">
    * Your token is scoped to a specific subdomain. Using it against a different domain (including `nudjdev` from a production token) returns 401.
    * Re-issue the token from the correct organisation's Developer Settings if you need to test against another tenant.
  </Accordion>

  <Accordion title="CORS errors">
    * The APIs are not CORS-enabled for browser origins. Proxy all requests through your own backend — do not call these endpoints directly from a browser.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Token formats, API auth headers, and how requests are scoped to your domain.
  </Card>

  <Card title="Custom Domain Setup (Admin)" icon="globe" href="/admin-guide/settings/domains">
    Full DNS and SSL walkthrough for registering a white-label domain.
  </Card>
</CardGroup>