The Springwinter API supports two authentication methods: API bearer tokens, which are recommended for all automation and programmatic access, and cookie sessions with CSRF tokens, which the browser dashboard uses internally. Choose bearer tokens for scripts, CI pipelines, and third-party integrations. Use the cookie + CSRF flow only if you are building a browser-based client that mirrors the Springwinter dashboard behaviour.
Method 1: Bearer Token (Recommended)
Bearer tokens are long-lived credentials you generate in the Springwinter dashboard. They authenticate every request without requiring a session cookie or CSRF validation, making them the simplest and most portable option for programmatic use.
Create a token
- Sign in to Springwinter at https://springwinter.dev/auth.
- Open Settings → API Tokens (see API Tokens).
- Click New token, give it a descriptive name, and confirm.
- Copy the token immediately — Springwinter shows it only once and cannot reveal it again.
Store your API token in a secrets manager or environment variable. Never commit it to source control or include it in client-side code.
Use the token
Pass the token in the Authorization header on every request:
Example
Bearer tokens bypass CSRF validation entirely, so you do not need to fetch a CSRF token when using this method.
Revoke a token
You can revoke a token at any time from Settings → API Tokens, or by calling DELETE /api/api_tokens/{id}. Revoked tokens are rejected immediately.
Method 2: Cookie Session + CSRF Token
The cookie session flow is used by the Springwinter browser dashboard. It requires two steps: establishing a session by signing in, then attaching a CSRF token to every mutating request. You can replicate this flow programmatically, but bearer tokens are simpler for most use cases.
Step 1 — Sign in and obtain a session cookie
Send your credentials to POST /api/session. On success, the server sets a session cookie that you must include in all subsequent requests.
The -c cookies.txt flag tells curl to save the session cookie to a file so you can reuse it across requests.
Step 2 — Fetch a CSRF token
Retrieve a CSRF token from GET /api/csrf. Pass the saved session cookie with -b cookies.txt:
The response returns a CSRF token value you must attach to all mutating requests.
Step 3 — Include the CSRF token on mutating requests
Add the X-CSRF-Token header to every POST, PATCH, PUT, and DELETE request:
GET requests do not require a CSRF token.
Sign out
Delete the active session by calling DELETE /api/session. Include the session cookie and CSRF token:
Error Responses
Use bearer tokens for all automated and programmatic use — scripts, CI/CD pipelines, infrastructure tooling, and third-party integrations. The cookie + CSRF flow is designed for the Springwinter browser UI and is more complex to manage outside a browser context.