API Endpoints

OAuth Endpoints

Authorization Endpoint

GET /oauth/auth

Initiates 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-urlencoded

Exchange 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:

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):

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "ey...",
  "scope": "openid profile"
}

Revocation Endpoint

POST /oauth/revocation
Content-Type: application/x-www-form-urlencoded

Revoke 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-urlencoded

Check 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/jwks

Returns 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:

{
  "device_code": "...",
  "user_code": "ABCD-1234",
  "verification_uri": "https://host/device",
  "expires_in": 600,
  "interval": 5
}

---

Admin Endpoints

All admin endpoints require authentication via Authorization: Bearer <admin_token> header (or legacy kAuth header).

Response envelope:

{
  "didSucceed": true,
  "data": { ... },
  "status": 200,
  "message": "optional message"
}

Auth

These endpoints are public (no auth required) unless noted.

Method	Path	Auth	Description
POST	/admin/auth/register	No	Create a new admin account
POST	/admin/auth/login	No	Sign in and receive a JWT
GET	/admin/auth/me	Yes	Get current user info
POST	/admin/auth/forgot-password	No	Request a password reset token
POST	/admin/auth/reset-password	No	Reset password with token
POST	/admin/auth/verify-email	No	Verify email with token
POST	/admin/auth/resend-verification	Yes	Resend verification email
POST	/admin/auth/refresh	Yes	Issue a fresh JWT
POST	/admin/auth/logout	Yes	Invalidate all sessions
PATCH	/admin/auth/profile	Yes	Update name
POST	/admin/auth/change-password	Yes	Change password (requires current password)
PATCH	/admin/auth/users/:id/deactivate	Yes	Deactivate an admin user

Clients

Method	Path	Description
GET	/admin/clients	List all OAuth clients
GET	/admin/clients/:id	Get client details with scopes
POST	/admin/clients	Create a new client
PUT	/admin/clients/:id	Update client metadata
DELETE	/admin/clients/:id	Deactivate a client
POST	/admin/clients/:id/rotate-secret	Generate a new client secret
PUT	/admin/clients/:id/scopes	Replace scopes assigned to a client

Create Client body:

{
  "client_name": "My App",
  "redirect_uris": ["https://myapp.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "client_secret_basic",
  "application_type": "web",
  "scope_ids": [1, 3, 5]
}

Scopes

Method	Path	Description
GET	/admin/scopes	List all available scopes
GET	/admin/scopes/:id	Get scope details
POST	/admin/scopes	Create a new scope
PUT	/admin/scopes/:id	Update a scope

Available scopes include:

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

See the full list in the OAuth Portal.

---

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 sync

Query 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