Authenticate with Ticket¶

Target Audience: Developers

Introduction¶

The Authenticate with Ticket operation is a server-to-server endpoint that allows you to authenticate a user into an SSO2 session using an authorization ticket obtained from Payway. This is useful when you have already obtained an authorization ticket through another authentication flow and want to establish or continue an SSO2 session.

Unlike the standard Authenticate operation which uses username and password, this operation uses a Payway authorization ticket to verify the user's identity.

Use Cases¶

Cross-system authentication: When transferring authentication state from another system that has already verified the user's identity
Service integration: When integrating services that have their own authentication mechanism but need to establish SSO2 sessions

Operation Flow¶

Client obtains an authorization ticket from Payway (through another authentication mechanism)
Client creates and signs a JWT containing the session ID and authorization ticket
Client makes a server-to-server POST request to the AuthenticateWithTicket endpoint
SSO2 validates the ticket with Payway
SSO2 updates the session state to logged in
SSO2 returns a Session Token with the logged-in state

Request¶

The request to the AuthenticateWithTicket endpoint is a server-to-server operation. You create an HTTP POST request with a JSON payload containing the encoded JWT. You sign the token with the secret related to the API-client that you use.

Endpoint¶

Environment	URI
Stage	https://payway-sso-stage.azurewebsites.net/authenticatewithticket
Production	https://sso.worldoftulo.com/authenticatewithticket

Request Parameters¶

Param	Description
t	Encoded JWT token

Request Example¶

curl --request POST \
  --url https://payway-sso-stage.azurewebsites.net/authenticatewithticket \
  --header 'Content-Type: application/json' \
  --data '{
    "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjaWQiOiI1NzIyMWYxMTU4NGQ1NGUyOGIwMDAwMDEiLCJzaWQiOiJmMGJjMTU4OC03ZWIwLWVmMTEtODhjZi0wMDBkM2FiYzA1ZGIiLCJhdCI6ImF1dGhvcml6YXRpb25fdGlja2V0X2Zyb21fcGF5d2F5IiwiaXBhIjoiMTkyLjE2OC4xLjEiLCJ1YXMiOiJNb3ppbGxhLzUuMCAoV2luZG93cyBOVCAxMC4wOyBXaW42NDsgeDY0KSIsIm5iZiI6MTczMjg3OTU5MCwiZXhwIjoxNzMyODc5NjUwLCJpYXQiOjE3MzI4Nzk1OTAsImlzcyI6ImFkZXByaW1vc2UiLCJhdWQiOiJwdy1zc28ifQ.example_signature"
  }'

JWT Structure¶

The decoded JWT in the above example looks like this:

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "cid": "57221f11584d54e28b000001",
  "sid": "f0bc1588-7eb0-ef11-88cf-000d3abc05db",
  "at": "authorization_ticket_from_payway",
  "ipa": "192.168.1.1",
  "uas": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "nbf": 1732879590,
  "exp": 1732879650,
  "iat": 1732879590,
  "iss": "adeprimose",
  "aud": "pw-sso"
}

JWT Claims¶

Claim	Type	Required	Description
cid	string	Yes	"Client ID", Your API-client ID
sid	string	Yes	"Session ID", The SSO2 session ID obtained from a previous Identify or CreateSession operation
at	string	Yes	"Authorization Ticket", A valid Payway authorization ticket
ipa	string	Yes	"IP Address", The user's IP address
uas	string	Yes	"User-Agent String", The user's browser User-Agent string
nbf	int(epoch)	Yes	"Not Before", This should be the epoch timestamp of when this token is created
exp	int(epoch)	Yes	"Expires", This should be the epoch timestamp for 10 seconds after token was created
iat	int(epoch)	Yes	"Issued At", This should be the epoch timestamp of when this token is created
iss	string	Yes	"Issuer", This should be your Payway Organisation ID
aud	string	Yes	"Audience", This should always be "pw-sso"

Response¶

The response is a JSON payload containing an encoded JWT Session Token.

Success Response Example¶

When authentication is successful, the session state will be updated to "loggedin":

{
  "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHMiOiJsb2dnZWRpbiIsInNpZCI6ImYwYmMxNTg4LTdlYjAtZWYxMS04OGNmLTAwMGQzYWJjMDVkYiIsImFpZCI6IjEyMzQ1Njc4OTBhYmNkZWYiLCJhdCI6Im5ld19hdXRob3JpemF0aW9uX3RpY2tldCIsImVyciI6bnVsbCwiZW1zIjoiIiwiZnJmIjotMSwicmFhIjotMSwic2xtIjowLCJvdHAiOiIiLCJzZXMiOiIiLCJuYmYiOjE3MzI4Nzk1OTAsImV4cCI6MTczMjg3OTY1MCwiaWF0IjoxNzMyODc5NTkwLCJpc3MiOiJwdy1zc28iLCJhdWQiOiI1NzIyMWYxMTU4NGQ1NGUyOGIwMDAwMDEifQ.example_signature"
}

The decoded JWT looks like this:

{
  "sts": "loggedin",
  "sid": "f0bc1588-7eb0-ef11-88cf-000d3abc05db",
  "aid": "1234567890abcdef",
  "at": "new_authorization_ticket",
  "err": null,
  "ems": "",
  "frf": -1,
  "raa": -1,
  "slm": 0,
  "otp": "",
  "ses": "",
  "nbf": 1732879590,
  "exp": 1732879650,
  "iat": 1732879590,
  "iss": "pw-sso",
  "aud": "57221f11584d54e28b000001"
}

Response Claims¶

Claim	Description
sts	Session state, will be "loggedin" on successful authentication
sid	The session ID, a unique identifier for the SSO2 session
aid	Payway account ID of the authenticated user
at	A new authorization ticket that can be exchanged for an access token with the user's identity
err	If something went wrong this field will hold an error code to help figure out the problem
ems	If something went wrong this field can hold an error message to help figure out the problem
frf	Frozen for seconds, -1 means not frozen
raa	Remaining authentication attempts, -1 means not applicable
slm	The current session limit configured, see Session limitations
otp	One time password, empty for this operation
ses	See Session limitations
nbf	This is the epoch timestamp of when this token is created
exp	This is the epoch timestamp for 10 seconds after token was created
iat	This is the epoch timestamp of when this token is created
iss	Will always be issued by "pw-sso"
aud	The client_id of the API-client the token was issued for

Error Handling¶

Error Response Example¶

{
  "t": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHMiOiJhbm9uIiwic2lkIjoiZjBiYzE1ODgtN2ViMC1lZjExLTg4Y2YtMDAwZDNhYmMwNWRiIiwiYWlkIjoiIiwiYXQiOm51bGwsImVyciI6ImludmFsaWRfdGlja2V0IiwiZW1zIjoiVGhlIGF1dGhvcml6YXRpb24gdGlja2V0IGlzIGludmFsaWQiLCJuYmYiOjE3MzI4Nzk1OTAsImV4cCI6MTczMjg3OTY1MCwiaWF0IjoxNzMyODc5NTkwLCJpc3MiOiJwdy1zc28iLCJhdWQiOiI1NzIyMWYxMTU4NGQ1NGUyOGIwMDAwMDEifQ.example_signature"
}

Error Codes¶

The error code can be found in the claim err. See general error codes for error codes not specific to this operation.

Operation-specific error codes:¶

Error code	Description
invalid_ticket	The authorization ticket provided is invalid or has expired
session_terminated	The session has been terminated and cannot be used for authentication
session_already_logged_in_on_another_account	The session is already logged in with a different account than the one associated with the ticket

Session State Requirements¶

The AuthenticateWithTicket operation can be performed on sessions in the following states:

Session State	Behavior
Anon	The user will be authenticated and the session will transition to "loggedin" state
LoggedIn	The operation will verify that the ticket matches the currently logged-in account
Terminated	The operation will fail with the error code "session_terminated"

Important

If a session is already in the "loggedin" state, the authorization ticket must be for the same Payway account that is currently logged into the session. If the accounts don't match, the operation will fail with error code "session_already_logged_in_on_another_account".

Security Considerations¶

Ticket validation: The authorization ticket is validated against Payway's authorization server to ensure authenticity
Account matching: When authenticating an already logged-in session, the system verifies that the ticket belongs to the same account
Session tracking: Each authentication attempt is logged in the session timeline with IP address and user agent information
Token expiration: JWT tokens should have a short expiration time (10 seconds recommended) to minimize risk of replay attacks

Implementation Notes¶

Store the session ID (sid) from previous Identify or CreateSession operations
Obtain a valid authorization ticket from Payway through your preferred authentication flow
Create and sign a JWT with all required claims
Make the server-to-server POST request
Handle the response and update your local session state accordingly
Exchange the new authorization ticket (at) from the response for an access token and store the access token for subsequent Payway API calls