Skip to main content

Terminal Login

Terminal Login is the process by which a payment terminal or mobile application authenticates with the Stitch system to obtain a JWT (JSON Web Token) for subsequent API calls. This token provides secure access to transaction processing and other terminal functions.

There are two ways to obtain a JWT:

  1. Through the Tenant's own authentication system
  2. Directly from the Stitch system (covered in this document)

For more information about these JWT models, see JWT authentication.

Authentication Process​

When using Stitch to generate the JWT, the terminal must:

  1. Be registered in the Stitch system
  2. Be allocated to a merchant
  3. Have a Login PIN set on the merchant account
  4. Use the Terminal Login API

API Authentication​

The Terminal Login endpoint is secured with an API Key. Your terminal or application must include this key in all requests:

HeaderDescription
x-api-keyThe API Key specifically created for terminal login capability

Login Request and Response​

POST /v/1/terminal-login
x-api-key: {{terminal_api_key}}
{
  "serialNumber": "{{serial_number}}",
  "pin": "{{pin}}"
}
  • serialNumber: The unique identifier of the terminal device (assigned by the manufacturer).
  • pin: The merchant's login PIN that was configured during merchant setup.

If successful, the login request will respond with a JSON object having 3 keys, id_token, access_token and expires_at:

{
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6IC...",
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6IC...",
  "expires_at": "2025-02-28T19:57:03.789929Z"
}
  1. id_token: This is a JWT which contains merchant profile information that can be displayed on the terminal.
  2. access_token: This is a JWT Used for all subsequent API calls as a Bearer token in the Authorization header.
  3. expires_at: This is when the access_token will expire in ISO8601 format (UTC). This expiration time is also embedded within the access_token as an epoch timestamp.

Token Expiration​

Access tokens have a limited lifespan. When a token expires, you have two options:

  1. Perform a silent login using the stored PIN (requires secure PIN storage).
  2. Prompt the user to re-enter their PIN.

APIs​