Single Sign On to Stax

1. Log in to your Stax account (production or sandbox).
2. Navigate to the API Keys section and generate a new API Key.
3. Store this API Key securely on your server.

Without URL Parameters:

• Suitable for server-to-server communications where you are acting as your own user.
• Not recommended for SSO or client-side usage.

With URL Parameters (user_id or user_email):

• Use when you need to authenticate on behalf of a specific user, such as in mobile apps or for SSO.
• Include the user_id or user_email in the URL parameters.

1. The response will include an ephemeral token valid for 24 hours.
2. Use this token in the Authorization header as a Bearer token for subsequent API calls.
3. Example:
   HTTP

   Authorization: Bearer EPHEMERAL_TOKEN

1. Use the ephemeral token to facilitate SSO for sub-merchants.
2. Redirect the user to the Stax platform with the token to log them in automatically.

You must complete the following steps to implement SSO into your software.

1. Create a Merchant in Stax to represent one of your sub-merchants.
2. Create your merchant's API Key.
3. Create a Stax user account using the merchant's API key.

Create a URL that grants your users SSO access to Stax or Self-Registration. This URL can be programmatically constructed and conveniently placed within a button.

Once authenticated, Stax will automatically direct the user to the specified page.

1. Request an ephemeral authentication token (See above.)
2. Begin constructing the URL by specifying the app's SSO page.
   • For Stax, https://app.staxpayments.com/#/sso/
   • For Self registration, http://signup.staxpayments.com/#/sso/
3. Pass in the ephemeral token as the JWT[] URL query parameter.
   • Example: jwt[]=myEphemeralToken
4. Designate the login redirect URL query parameter.
   • This value is the page within Stax Pay or Stax Signup Pages where the user will be redirected after successful authentication. This value should be URL-encoded.
   • Note: if the loginRedirect or redirect URL parameter is not provided, the user will be redirected to the app's homepage.

Stax Signup Pages

• URL parameter is named redirect
• Example: Stax Signup Pages Review Page &redirect=application%2Freview

Stax Pay

• URL parameter is named loginRedirect
• Example: Stax Pay Deposit Report page, with start- and end-date parameters &loginRedirect=report%2Fdeposit-report%3FstartDate%3D2020-01-01%252000%253A00%253A00%26endDate%3D2020-09-25%252023%253A59%253A59%26timezone%3DEDT%26order%3DDESC%26page%3D1

Build the Full SSO URL

• Example of full URL granting SSO into Stax Pay: https://app.staxpayments.com/#/sso?loginRedirect=report%2Fdeposit-report%3FstartDate%3D2020-01-01%252000%253A00%253A00%26endDate%3D2020-09-25%252023%253A59%253A59%26timezone%3DEDT%26order%3DDESC%26page%3D1&jwt[]=myEphemeralToken
• Example of full URL granting SSO into the Signup Pages: https://signup.staxpayments.com/#/sso?redirect=application%2Freview&jwt[]=myEphemeralToken

Error Message: "You do not have permission to request tokens for other users."

Cause: Attempting to generate an ephemeral token for a Stax Connect level user or a user not on the same team.

Solution: Ensure you are requesting tokens only for non-Stax Connect users on the same merchant team.

Error Message: "Invalid API Key."

Cause: The API Key provided in the Authorization header is invalid or expired.

Solution: Verify that you are using a valid, active API Key generated from your Stax account.

Issue: Attempting to perform SSO without specifying user_id or user_email.

Solution: Always include user_id or user_email in the URL parameters when generating an ephemeral token for SSO.

Error Message: "Token has expired."

Cause: The ephemeral token has expired after 24 hours.

Solution: Generate a new ephemeral token using your API Key.