Authentication - Nextoria Hub

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

Go to Settings → API → New API Key
Give the key a descriptive name (e.g. “Zapier Integration”)
Select scopes (see Scopes below)
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:

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

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.

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

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:

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:

{
  "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:

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:

{
  "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)

​Overview

​API Keys

​Generating an API Key

​Using Your API Key

​Scopes

​OAuth 2.0

​Application Registration

​Authorization Flow

​Rate Limits

​Error Responses

Overview

API Keys

Generating an API Key

Using Your API Key

Scopes

OAuth 2.0

Application Registration

Authorization Flow

Rate Limits

Error Responses