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:
- Through the Tenant's own authentication system
- 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:
- Be registered in the Stitch system
- Be allocated to a merchant
- Have a Login PIN set on the merchant account
- 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:
Header | Description |
---|---|
x-api-key | The 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"
}
id_token
: This is a JWT which contains merchant profile information that can be displayed on the terminal.access_token
: This is a JWT Used for all subsequent API calls as a Bearer token in the Authorization header.expires_at
: This is when theaccess_token
will expire in ISO8601 format (UTC). This expiration time is also embedded within theaccess_token
as an epoch timestamp.
Token Expiration
Access tokens have a limited lifespan. When a token expires, you have two options:
- Perform a silent login using the stored PIN (requires secure PIN storage).
- Prompt the user to re-enter their PIN.