Zum Hauptinhalt springen

Rest API

Seatsurfing provides and uses a couple of REST APIs. The REST APIs are used by the mobile and web app as well as the administrator web interface.

Authorization checks​

Each API function is protected by authorization checks:

  • First check: Role of the user (anonymous, user, org admin, super admin)
  • Second check: Organization membership

Status Codes​

Seatsurfing's REST API uses the well known HTTP status codes to inform the caller about the result and eventual errors:

  • 201 Created: Object created (includes HTTP response header X-Object-ID)
  • 204 No Content: Object updated or no response content
  • 400 Bad Request: Malformed request or incomplete JSON
  • 401 Unauthorized: JWT in HTTP request header Authorization missing, expired or invalid
  • 403 Forbidden: Authorized, by user has no access to requested resource
  • 404 Not found: Object not found
  • 409 Conflict: Conflicting request
  • 500 Internal Server Error

Roles​

  • Anonymous: Every user allowed, no authorization required
  • User: Authorized user who is a member of an organization
  • Org Admin: An organization's administrator
  • Super Admin: Global administrator with access to all organizations and all functions

Session management​

Token lifetimes​

  • Access Token Lifetime: 15 minutes
  • Refresh Token Lifetime: 1 day
  • Access Token Refresh in Seatsurfing's web frontends: 5 minutes

Storage locations in web frontends​

  • Session Storage:
    • Access Token
    • Access Token Expiry Timestamp
    • Logout URL
  • Local Storage:
    • Refresh Token

Authentication flow in web frontends​

  • When logging in:
    • Access Token is stored in browser's session storage via AjaxConfigBrowserPersister.
    • Refresh Token is stored in browser's local storage via AjaxConfigBrowserPersister.
  • When performing a page reload in the browser:
    • Check if Access Token is present in session storage.
    • If no Access Token was found, check if Refresh Token is present in Local Storage. If so, try to retrieve a new Access Token using the Refresh Token.
    • Use the Access Token to fetch the current user's details.
    • If fetching the user's details fails due to invalid Access Token, delete all credentials from the session and local Storages and perform redirect to login page.
  • When performing an AJAX Call:
    • Check if a Access Token with sufficient remaining validity period (expiry timestamp) exists in session storage.
    • If the Access Token needs to be refreshed and a Refresh Token exists, retrieve a new Access Token using the Refresh Token and store Access and Refresh Token in session/local storage. If retrieving a new Access Token fails, delete all credentials from the session and local storage.
    • If a valid Access Token exists, perform the actual AJAX Call.

Endpoints​

Please refer to the OpenAPI specs which can be found in the project's repository.