Auth

Point of Service API Authentication Flow

The Point of Service (POS) API admin panel uses Basic authentication and the OAuth Resource Owner Password Credentials (ROPC) Flow.

To provide the proper experience for admins using the POS admin panel, you’ll need to provide the following capabilities:

1. Create an account
2. Log in to the admin panel
3. Refresh an account’s access token

Step 1: Create account

The user will first create their account for the POS admin client app.

Request

The client sends an HTTP request to the /users endpoint, including the user_name, password, and grant_type properties in the request body.

Endpoint: POST /users

curl -X 'POST' \
  'https://reimagined-journey-g45xxv4v6gwhvrrr-80.app.github.dev/users' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic {basicAuthToken}' \
  -H 'content-type: application/json' \
  -d '{
    "grant_type": "password",
    "user_name": "my-user-name",
    "password": "my-secure-password"
  }'

Response

If the request was successful, the server responds with a 201 Created status code with the response body containing the new user account resource.

Step 2: Log in as the admin

Admin users will log into the admin portal to perform actions like creating users and dishes or adding/updating ingredients. To send requests to admin endpoints, the client app requires an access token which is obtained by making a POST call to the /auth/token endpoint.

Request

The client sends an HTTP request that includes a basic authorization header and the user’s user_name and password.

Endpoint: POST /auth/token

curl -X 'POST' \
  'https://reimagined-journey-g45xxv4v6gwhvrrr-80.app.github.dev/auth/token' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic {base64EncodedclientidclientSecret}' \
  -H 'content-type: application/json' \
  -d '{
    "grant_type": "password",
    "user_name": "my-user-name",
    "password": "my-secure-password"
  }'

Response

If the request was successful, the server responds with a 201 Created status code with an access token in the response body.

Response body properties:

Property	Type	Description
access_token	string	The UUID used for authentication, required for accessing protected endpoints
expires_in	integer	The time, in seconds, the access token remains valid
refresh_token	string	The value of the refresh token, used to obtain the new access token after it expires
token_type	string	The type of access token, which will always be Bearer

Step 3: Refresh the access token

After the access_token expires, you can refresh the access token by sending a POST call to the /auth/refresh-token endpoint.

Request

The client sends an HTTP request using the refresh_token value in the authorization header.

Endpoint: POST /auth/refresh-token

curl -X 'POST' \
  'https://reimagined-journey-g45xxv4v6gwhvrrr-80.app.github.dev/auth/refresh-token' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {refreshToken}' \
  -d ''

Response

If the request was successful, the server responds with a 201 Created status code with the response body containing the new access and refresh tokens.