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.
Personal API tokens
Section titled “Personal API tokens”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.
OAuth 2.0 and OpenID Connect
Section titled “OAuth 2.0 and OpenID Connect”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.
Grant types supported
Section titled “Grant types supported”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.
Endpoints
Section titled “Endpoints”| 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 client registration
Section titled “OAuth client registration”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.
Scopes
Section titled “Scopes”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.
Tokens
Section titled “Tokens”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.
Using an access token
Section titled “Using an access token”Pass it as a Bearer token in the Authorization header:
GET /v1/observations HTTP/1.1Host: api.skynetgo.orgAuthorization: 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.
Refreshing
Section titled “Refreshing”OAuth access tokens expire after one hour. Exchange the refresh token at the token endpoint:
POST /oauth2/token HTTP/1.1Host: api.skynetgo.orgContent-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.
SkyNode installation tokens
Section titled “SkyNode installation tokens”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.
Session cookies (web app)
Section titled “Session cookies (web app)”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.
Things to confirm before going live
Section titled “Things to confirm before going live”- 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.