Authentication

• our API uses short-lived access tokens (JWT) and longer-lived refresh tokens.
• You can carry the access token in the Authorization header or rely on secure cookies set during login.

Login

Use the login mutation with user credentials. On success you’ll receive:

• token: access token (JWT)
• refreshToken: refresh token
• expiresIn: access token lifetime in seconds (typically 3600)

mutation Login($email: String!, $password: String!) {
    login(email: $email, password: $password) {
        token
        refreshToken
        expiresIn
    }
}

Tip: If you are using a browser client, the server may also set secure cookies for you: _trp (access) and _trpr (refresh).

Sending Authenticated Requests

Include the access token as a bearer token in each request.

curl -X POST "$GRAPHQL_ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "query { user { id email } }"
  }'

If you are using cookies (browser flows), requests will be authenticated automatically when the cookies are present and valid.

Token Lifetimes

• Access token: ~1 hour (returns expiresIn: 3600)
• Refresh token: ~7 days

Plan to refresh the access token before it expires, or handle 401/Unauthorized responses by triggering a refresh.

Refreshing the Access Token

Use the refreshToken mutation to obtain a new access token. You can supply the refresh token explicitly, or omit it and rely on the refresh cookie if set.

mutation Refresh($refreshToken: String) {
    refreshToken(refreshToken: $refreshToken) {
        token
        refreshToken
        expiresIn
    }
}

Notes:

• If you pass refreshToken, it must match the stored refresh token for your user.
• If omitted, the server will read the refresh token from the secure cookie when available.
• The mutation returns a new access token; the refresh token may remain the same unless rotated by the server.

Cookies vs Headers

• Headers: Works in any client. Send Authorization: Bearer <token>.
• Cookies: In browser flows, secure cookies (_trp for access, _trpr for refresh) may be set. They are Secure and SameSite=Strict.
• You can mix approaches: use cookies in the browser and still attach the Authorization header for API calls from your backend.

Error Handling

Common authentication errors and suggested actions:

• Unauthorized: No token provided — Ensure the Authorization header or access cookie is present.
• Unauthorized: Token verification failed — Access token is invalid or expired; refresh and retry.
• No refresh token provided — Pass the refresh token or ensure the refresh cookie is set.
• Invalid refresh token — Token mismatch or tampering detected; prompt for re-login.
• Refresh token expired — Refresh session has ended; prompt for re-login.

Sign-out

• Clients should remove stored tokens (and clear cookies if applicable). If you need server-side revocation of a refresh token, contact support for guidance.

Best Practices

• Prefer short-lived access tokens and refresh as needed.
• Store tokens securely; avoid exposing them to untrusted scripts.
• In SPAs, prefer secure, HTTP-only cookies for refresh; attach access tokens via header for API calls.
• Handle 401 by attempting a single refresh, then redirect to login if it fails.