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
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 |
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
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
{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "dGh...",
"scope": "projects:read tasks:read"
}
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 |
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) |
