Appearance
API Endpoints
OAuth Endpoints
Authorization Endpoint
GET /oauth/authInitiates an OAuth 2.0 authorization flow. Redirects the user to the login/consent page.
| Parameter | Type | Required | Description |
|---|---|---|---|
response_type | string | Yes | code for authorization code flow |
client_id | string | Yes | Your OAuth client ID |
redirect_uri | string | Yes | Registered redirect URI |
scope | string | Yes | Space-separated list of scopes |
state | string | Recommended | Random string for CSRF prevention |
code_challenge | string | Yes (PKCE) | S256 code challenge |
code_challenge_method | string | Yes (PKCE) | Must be S256 |
Token Endpoint
POST /oauth/token
Content-Type: application/x-www-form-urlencodedExchange an authorization code, refresh token, client credentials, or device code for an access token.
Authorization Code:
| Parameter | Description |
|---|---|
grant_type | authorization_code |
code | The authorization code |
redirect_uri | Must match the original request |
client_id | Your client ID |
client_secret | Your client secret |
code_verifier | PKCE code verifier |
Client Credentials (a server-to-server app acting as its owner vouches, the company's API user or the owning user; see Client Credentials):
| Parameter | Description |
|---|---|
grant_type | client_credentials |
client_id | Your client ID |
client_secret | Your client secret |
scope | Requested scopes |
Refresh Token:
| Parameter | Description |
|---|---|
grant_type | refresh_token |
refresh_token | The refresh token |
client_id | Your client ID |
client_secret | Your client secret |
Device Code:
| Parameter | Description |
|---|---|
grant_type | urn:ietf:params:oauth:grant-type:device_code |
device_code | The device code |
client_id | Your client ID |
Response (all grant types):
json
{
"access_token": "eyJhbG...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "ey...",
"scope": "openid profile"
}Revocation Endpoint
POST /oauth/revocation
Content-Type: application/x-www-form-urlencodedRevoke an access token or refresh token. See Token Revocation for details.
| Parameter | Description |
|---|---|
token | The token to revoke |
token_type_hint | access_token or refresh_token |
client_id | Your client ID |
client_secret | Your client secret (confidential clients) |
Introspection Endpoint
POST /oauth/introspection
Content-Type: application/x-www-form-urlencodedCheck whether a token is active. Returns { "active": true, ... } or { "active": false }.
| Parameter | Description |
|---|---|
token | The token to inspect |
client_id | Your client ID |
client_secret | Your client secret (confidential clients) |
JWKS Endpoint
GET /oauth/jwksReturns the JSON Web Key Set for verifying access token signatures.
Device Authorization Endpoint
POST /oauth/device/authorize
Content-Type: application/x-www-form-urlencoded| Parameter | Description |
|---|---|
client_id | Your client ID |
scope | Requested scopes |
Response:
json
{
"device_code": "...",
"user_code": "ABCD-1234",
"verification_uri": "https://host/device",
"expires_in": 600,
"interval": 5
}Scopes
Register your application and choose its scopes in the developer portal. Tokens carry the scopes granted to your client; each REST endpoint names the scope it requires.
| Scope | Description |
|---|---|
openid | OpenID Connect scope |
profile | User profile information |
projects:read | Read projects |
projects:write | Create/update projects |
invoices:read | Read invoices |
invoices:write | Create/update invoices |
time:read | Read time entries |
time:write | Create/update time entries |
admin | Full admin access (all scopes) |
read | Read access to all resources |
write | Write access to all resources |
The developer portal lists every scope your client can be granted.
REST API Endpoints
All REST API endpoints require Authorization: Bearer <access_token>. See the Resource API and Query API guides for full details.
Special Endpoints
| Method | Path | Scope | Description |
|---|---|---|---|
| GET | /api/v1/me | any | Current user info and granted scopes |
| GET | /api/v1/company | any | Company information |
| GET | /api/v1/settings | any | Company settings |
| GET | /api/v1/valid | any | Validate token, returns granted scopes |
Resource CRUD
Standard CRUD endpoints are generated for 21 resource types. See the Resource API guide for the full list, supported methods, query parameters, and response formats.
GET /api/v1/{resource} # List (paginated)
GET /api/v1/{resource}/:id # Get by ID
POST /api/v1/{resource} # Create
PUT /api/v1/{resource}/:id # Full update
PATCH /api/v1/{resource}/:id # Partial update
DELETE /api/v1/{resource}/:id # Delete
GET /api/v1/{resource}/search?q= # Search
GET /api/v1/{resource}/since/:ts # Delta syncQuery API
Batch queries and advanced filtering. See the Query API guide.
POST /api/v1/query # Batch query (multiple models)
POST /api/v1/query/:modelName # Single model query
POST /api/v1/query/:modelName/:id # Find by ID