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

# Authentication

> Authenticate with the Nextoria Hub API using API keys or OAuth 2.0.

## Overview

The Nextoria Hub REST API uses **API key** authentication for server-to-server integrations and **OAuth 2.0** for user-delegated access. All API requests must be made over HTTPS.

**Base URL:**

```
https://api.nextoriahub.com/v1
```

## API Keys

API keys are the recommended authentication method for server-side integrations (webhooks, automation, data exports).

### Generating an API Key

1. Go to **Settings → API → New API Key**
2. Give the key a descriptive name (e.g. "Zapier Integration")
3. Select scopes (see [Scopes](#scopes) below)
4. Copy the generated key — it is shown **only once**

### Using Your API Key

Pass your API key as a Bearer token in the `Authorization` header:

```bash theme={null}
curl https://api.nextoriahub.com/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Scopes

| Scope            | Description                          |
| ---------------- | ------------------------------------ |
| `projects:read`  | List and read project data           |
| `projects:write` | Create, update, and delete projects  |
| `tasks:read`     | Read task data across projects       |
| `tasks:write`    | Create and update tasks              |
| `clients:read`   | Read client records                  |
| `clients:write`  | Create and manage client records     |
| `invoices:read`  | Read invoice data                    |
| `invoices:write` | Create, send, and void invoices      |
| `files:read`     | Read file metadata and download URLs |
| `analytics:read` | Read analytics and reporting data    |

<Warning>
  API keys have access to your entire workspace within their granted scopes.
  Treat them like passwords — never commit them to source control or share them
  publicly.
</Warning>

## OAuth 2.0

For user-facing integrations (e.g. allowing a third-party app to act on behalf of a specific Nextoria Hub user), use the OAuth 2.0 Authorization Code flow.

### Application Registration

Register your OAuth application at **Settings → API → OAuth Applications → Register App**:

| Field            | Description                                |
| ---------------- | ------------------------------------------ |
| **App Name**     | Display name shown on the consent screen   |
| **Redirect URI** | Where to send the user after authorization |
| **Logo**         | Optional — shown on the consent screen     |

After registration, you'll receive a `client_id` and `client_secret`.

### Authorization Flow

**Step 1: Redirect the user to the authorization endpoint:**

```
GET https://app.nextoriahub.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=projects:read+tasks:read
  &state=RANDOM_STATE_STRING
```

**Step 2: Exchange the authorization code for a token:**

```bash theme={null}
POST https://api.nextoriahub.com/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https://yourapp.com/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
```

**Response:**

```json theme={null}
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGh...",
  "scope": "projects:read tasks:read"
}
```

**Step 3: Use the access token in API requests:**

```bash theme={null}
curl https://api.nextoriahub.com/v1/projects \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

## Rate Limits

| Plan    | Requests per minute | Burst limit |
| ------- | ------------------- | ----------- |
| Starter | 60                  | 100         |
| Growth  | 300                 | 500         |
| Scale   | 1,000               | 2,000       |

Exceeding the rate limit returns a `429 Too Many Requests` response with a `Retry-After` header indicating when to retry.

## Error Responses

All API errors follow a consistent format:

```json theme={null}
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Project with ID proj_abc123 was not found.",
    "status": 404
  }
}
```

| HTTP Status | Code             | Description                      |
| ----------- | ---------------- | -------------------------------- |
| 400         | `BAD_REQUEST`    | Invalid request parameters       |
| 401         | `UNAUTHORIZED`   | Missing or invalid API key       |
| 403         | `FORBIDDEN`      | Valid key but insufficient scope |
| 404         | `NOT_FOUND`      | Resource does not exist          |
| 422         | `UNPROCESSABLE`  | Validation errors                |
| 429         | `RATE_LIMITED`   | Too many requests                |
| 500         | `INTERNAL_ERROR` | Server error (report to support) |