Skip to main content

API Authentication

SVRunner uses session-based API authentication. Clients log in once, receive a session token, and send that token with subsequent requests.

Authentication Model​

The current API model is:

  1. call the login mutation
  2. receive a sessionToken
  3. store that token client-side
  4. send the raw token in the Authorization header on later HTTP requests

The current web client does not prepend Bearer to the token. It sends the session token directly.

Login Mutation​

The login mutation accepts a LoginInput with:

  • username, or
  • emailAddress
  • password

The response includes:

  • user
  • sessionToken

Example:

mutation Login($input: LoginInput!) {
  login(input: $input) {
    user {
      id
      username
      role
    }
    sessionToken
  }
}

Example variables using username:

{
  "input": {
    "username": "operator1",
    "password": "example-password"
  }
}

Example variables using email address:

{
  "input": {
    "emailAddress": "operator@example.com",
    "password": "example-password"
  }
}

Sending The Session Token​

After login, send the returned token in the Authorization header.

Example HTTP header:

Authorization: <sessionToken>

This is important: the current server resolves the authenticated user by reading request.headers.authorization directly and matching that value to User.sessionToken.

Example HTTP Request​

curl "http://localhost:7376/graphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_SESSION_TOKEN" \
  --data '{
    "query": "query GetUser($id: Int!) { user(id: $id) { id username role } }",
    "variables": { "id": 1 }
  }'

Session Reuse​

If a request is already authenticated and the server recognizes the current session, the login mutation can return the existing session state rather than forcing a brand new session flow.

For integrators, the important point is simple:

  • store the session token you receive
  • reuse it until you explicitly log out or the session becomes invalid

Logout​

The logout mutation requires an authenticated session.

When logout succeeds, the server clears the user's session token.

Example:

mutation Logout {
  logout {
    id
    username
  }
}

After logout:

  • discard the token client-side
  • expect future authenticated requests with that token to fail

Common Failure Cases​

Invalid Password​

If the username or email is correct but the password is wrong, login fails.

Missing Authorization Header​

If you forget to send the Authorization header on an authenticated request, the request will behave as unauthenticated.

Using Bearer​

If your client automatically prefixes the token with Bearer , confirm that your integration removes it unless you have added custom compatibility handling. The current implementation expects the raw token value.

Subscription Auth Caveat​

HTTP authentication is clear in the current code path. WebSocket subscription authentication is less clear, because the client setup does not obviously send connectionParams and the server websocket context is initialized without a request object.

Do not assume subscription auth behaves the same way as HTTP auth without validating it directly in your deployment.

API Login Session Token Stub screenshot: GraphQL client showing a successful login mutation and the returned sessionToken. Save final image at packages/docs/screenshots/api-authentication-login.png.