Skip to content

Authentication

Every request to the public API carries an access token. There are two ways to get one: a personal API token you create for yourself in the web app (the quickest path for scripts), or an OAuth 2.0 / OpenID Connect flow for applications that act on behalf of other users. The same tokens authorize HTTP requests and WebSocket connections.

For your own scripts and notebooks, create a token under Settings → API Tokens on your profile in the web app (https://skynetgo.org/u/<your-slug>/settings/api-tokens). The token value is shown once, when you create it; store it like a password. The same operation is available over the API as POST /v1/users/{slug}/tokens (list with GET, revoke with DELETE /v1/users/{slug}/tokens/{tokenId}); you can only manage your own tokens.

Personal tokens do not expire. Revoke a token when you no longer need it.

When you create a token you can optionally restrict it to a set of scopes (see Scopes). A token created with no scopes carries your full authority, the same as a signed-in session. A scoped token can only reach the read and edit routes its scopes allow, and cannot create new observations — use an unscoped token for the quickstarts.

Applications that sign users in with their Skynet account use the authorization-code flow. The public API is an OpenID Connect provider; its discovery document at https://api.skynetgo.org/.well-known/openid-configuration lists every endpoint below.

The token endpoint supports the authorization_code and refresh_token grants. There is no client_credentials, password, or implicit flow.

If you’re building a server-side integration that runs without an interactive user — what you’d usually do with client_credentials — use a personal API token belonging to the account the integration acts as.

Step Method + path
Authorization GET https://auth.skynetgo.org/authorize
Token (code exchange and refresh) POST https://api.skynetgo.org/oauth2/token
User info GET https://api.skynetgo.org/oauth2/userinfo
Revoke POST https://api.skynetgo.org/oauth/revoke
Signing keys (JWKS) GET https://api.skynetgo.org/.well-known/jwks.json

The authorization endpoint lives on the auth service; the token, user-info, and revocation endpoints are served by the public API.

The token endpoint takes a form-encoded body (application/x-www-form-urlencoded) with snake_case parameter names, as RFC 6749 specifies. Confidential clients authenticate with client_secret in the body or with HTTP Basic auth. Token-endpoint errors mostly use the RFC 6749 shape ({"error": "invalid_grant", "error_description": "..."}); a rejected authorization code or PKCE verifier returns a 400 with the {detail} envelope the rest of the API uses.

PKCE is required for public clients (clients without a secret) and optional for confidential clients. Send code_challenge and code_challenge_method (S256 or plain) on the authorize request and code_verifier on the code exchange. Authorization codes are single-use and expire after 10 minutes.

A successful exchange returns access_token, token_type (Bearer), expires_in (3600 seconds), refresh_token, scope (when scopes were requested), and an id_token (a signed RS256 JWT whose sub is the user’s uid).

OAuth clients are registered by the Skynet team; there is no self-service client registration. Each client has:

  • A client ID and, for confidential clients, a client secret.
  • A list of redirect URIs the auth server will permit.
  • A list of allowed scopes — the scopes this client may request.
  • A first-party flag. First-party clients (the official web app, SkyNode) skip the consent screen. Third-party clients show a consent screen the first time a user authorizes them; the approval is remembered until the user disconnects the app (DELETE /v1/me/connected-apps/{clientId}, or from the web app).

To register an integration as an OAuth client, contact the Skynet team.

A token issued without a scope carries the user’s full authority. A token issued with scopes is limited: it can reach only the API routes those scopes cover, and every other /v1 route returns 403.

The scopes you can put on a personal token (listed by GET /v1/token-scopes):

Scope Grants
observations:read View your observations, their tasks, requests, assets, and specs.
observations:write Edit, cancel, retarget, and apply specs to existing observations. Cannot create new observations.
files:read File metadata, image data, FITS, and presigned download URLs.
telescopes:read Telescopes, observatories, sites, devices, instruments, and their status snapshots.
accounts:read Observing accounts, grants, quotas, transactions, and activity.
accounts:write Create and modify observing accounts, grants, and quotas you control.

An OAuth client requests scopes with the space-delimited scope parameter on the authorize request; each must be in the client’s allowed scopes or the request is rejected with invalid_scope. The OpenID Connect scopes openid, email, and profile are also recognized. Any scoped token may call GET /v1/me.

If you find an endpoint your token won’t reach, the scope is the most likely cause.

All tokens — personal tokens, OAuth access and refresh tokens, and the tokens SkyNode installations use — are opaque strings stored server-side (only the OpenID Connect id_token is a JWT). A token is bound to either a user or a SkyNode installation, never both, and records the OAuth client that minted it, if any.

Pass it as a Bearer token in the Authorization header:

GET /v1/observations HTTP/1.1
Host: api.skynetgo.org
Authorization: Bearer <access-token>

The API also accepts a ?token= query parameter, but proxies and browser history record query strings, so prefer the header.

For WebSocket connections, pass the token in the Authorization header, as the subprotocol pair Sec-WebSocket-Protocol: skynet-token, <token> (the browser-friendly option), or in the ?token= query string — see WebSocket protocol.

OAuth access tokens expire after one hour. Exchange the refresh token at the token endpoint:

POST /oauth2/token HTTP/1.1
Host: api.skynetgo.org
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=<refresh-token>&client_id=<client-id>

Confidential clients also send client_secret. The response has the same shape as the code exchange. Refresh tokens are single-use: each refresh returns a new refresh_token, and you must use the new one from then on. User refresh tokens expire after 30 days.

A SkyNode installation is paired with an observatory or telescope by a user with authority over it, who signs in to SkyNode with the normal authorization-code flow. SkyNode then registers the installation and receives a refresh token tied to that installation, which does not expire; SkyNode refreshes its access token automatically through the same /oauth2/token endpoint.

For owners managing SkyNode installs, see SkyNode → Installation.

The web app manages its own browser session on top of OAuth. For API integrations, use bearer tokens rather than trying to drive the web app’s session; cookies are a detail of the web app.

  • Start with read-only calls. There is one environment, so anything your integration creates is real: it is scheduled and charged.
  • Verify your token’s scopes cover every endpoint your integration hits. The fastest way is to call each endpoint once and see what rejects.
  • Implement refresh-token rotation handling — when refresh returns a new refresh token, replace the old one immediately.
  • Decide where the tokens live. Treat them as secrets.