Authentication

Secure API requests with scoped bearer tokens.

Northstar authenticates API requests with bearer tokens. Tokens belong to a workspace and are limited by scopes selected at creation time.

Send a token

Include the token in the Authorization header:

http

Authorization: Bearer YOUR_TOKEN

bash

curl https://api.northstar.example/v1/projects \
  --header "Authorization: Bearer $NORTHSTAR_TOKEN"

Available scopes

Scope	Access
projects:read	View projects and their status
projects:write	Create and update projects
deployments:read	View releases and logs
deployments:write	Create and cancel deployments
webhooks:write	Manage webhook endpoints

Use the smallest set of scopes required by each integration.

Token safety

Store production tokens in a secret manager
Use separate tokens for development and production
Rotate tokens on a regular schedule
Revoke a token immediately if it appears in logs or source control

Authentication failures

A missing or invalid token returns 401 Unauthorized. A valid token without the required scope returns 403 Forbidden. Both responses include a request identifier and structured error body.

Configuration

API overview