Skip to main content

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: the permissions granted by the roles assigned to the calling user
  • Second check: organization membership — no request ever reaches data belonging to another organization

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

Permissions​

Access is granted by roles, which an organization's administrators define. Each role grants a set of permissions — users, groups, areas, bookings, settings and so on — at a level of no access, read, limited or full. A user may hold several roles and holds the highest level any of them grants. See Roles and Permissions for the full model.

Every authenticated user, regardless of the roles they hold, can always manage their own bookings, buddies, preferences and profile, and can read the areas and spaces available to them. Endpoints covering that baseline require no particular permission.

Endpoints reachable without authentication at all are documented as such in the OpenAPI specification.

Service accounts​

A service account is an account type rather than a role: it calls the API and cannot sign in to the web interfaces. It is assigned roles like any other user, so a token can be scoped narrowly. Read-only service accounts are additionally restricted to GET requests, whatever their roles grant.

Authenticate either with HTTP Basic Authentication, using {organizationId}_{email} as the username, or with an API token as a bearer token.

Session management​

Token lifetimes​

  • Access Token Lifetime: 15 minutes
  • Refresh Token Lifetime: 28 days
  • 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.