---
updatedAt: 2026-09-11T20:23:56.000Z
agentTools:
  projectIndex: https://docs.staxpayments.com/llms.txt
---

# Single Sign On to Stax 

Enable SSO for sub-merchants by generating an ephemeral token with specific URL query parameters.

This allows sub-merchants to access the Stax platform seamlessly through your application without requiring separate login credentials, enabling merchants to complete onboarding questions so they can get processing more quickly.

## Ephemeral Authentication Tokens

An ephemeral authentication token is a temporary token that expires after 24 hours. It is used to authenticate API calls securely without exposing your long-term API Key. By using ephemeral tokens, you can maintain the security of your API Key while allowing clients or browsers to make authenticated requests.

### Key Benefits

<Cards columns={3}>
  <Card title="Enhanced Security" icon="fa-shield-alt">
    Keep your long-term API Key secure on your server.
  </Card>

  <Card title="Temporary Access" icon="fa-clock">
    Tokens expire after 24 hours, reducing the risk if compromised.
  </Card>

  <Card title="Flexibility" icon="fa-mobile-alt">
    Use tokens for mobile SDKs or to enable Single Sign-On (SSO) for sub-merchants.
  </Card>
</Cards>

### Use Cases

<Tabs>
  <Tab title="Single Sign-On (SSO)">
    Enable SSO for sub-merchants by generating an ephemeral token with specific URL query parameters.

    This allows sub-merchants to access the Stax platform seamlessly through your application without requiring separate login credentials.
  </Tab>

  <Tab title="Mobile SDK Integration">
    Use ephemeral tokens with our mobile SDKs to authenticate API calls from mobile applications without embedding your long-term API Key in the app.

    This approach ensures that your sensitive API credentials never leave your secure server environment while still enabling mobile applications to make authenticated requests.
  </Tab>
</Tabs>

## Implementing Ephemeral Tokens

  <Accordion title="Step 1: Generate an API Key" icon="fa-key">
    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.
  </Accordion>

<Accordion title="Step 2: Request an Ephemeral Token" icon="fa-exchange-alt">
  **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.
</Accordion>

<Accordion title="Step 3: Use the Ephemeral Token" icon="fa-code">
  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
     ```
</Accordion>

<Accordion title="Step 4: Implement SSO (If Applicable)" icon="fa-sign-in-alt">
  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.
</Accordion>

## SSO to Stax

Send your merchants to Stax via SSO to use reports and functionality that you haven't added to your platform.

**Merchants can use Stax to:**

* Perform voids and refunds via their payments list.
* View and download their deposits.
* View their disputes.
* Download monthly processing statements.

To do this, you will add a button to your application that directs your sub-merchant to the desired location in Stax.

<Accordion title="Prerequisites" icon="fa-list-check">
  You must complete the following steps to implement SSO into your software.

  1. [Create a Merchant](https://api-docs.staxpayments.com/reference/create-a-merchant#/) in Stax to represent one of your sub-merchants.
  2. [Create your merchant's API Key](https://api-docs.staxpayments.com/reference/create-a-new-api-key-for-merchant#/).
  3. [Create a Stax user account using the merchant's API key](https://api-docs.staxpayments.com/reference/create-a-new-team-member#/).
</Accordion>

<Accordion title="Request SSO into Stax" icon="fa-link">
  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](https://api-docs.staxpayments.com/reference/ephemeral-authentication-tokens-1#/) (See above.)
  2. Begin constructing the URL by specifying the app's SSO page.
     * For Stax, [https://app.staxpayments.com/#/sso/](https://app.staxpayments.com/#/sso/)
     * For Self registration, [http://signup.staxpayments.com/#/sso/](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](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](https://signup.staxpayments.com/#/sso?redirect=application%2Freview\&jwt\[]=myEphemeralToken)
</Accordion>

## Security Recommendations

<Cards columns={2}>
  <Card title="Protect API Keys" icon="fa-lock">
    Never expose your long-term API Key to clients, browsers, or mobile applications. Always keep API Keys secured on your server.
  </Card>

  <Card title="Use HTTPS" icon="fa-shield-alt">
    Ensure all API calls are made over HTTPS to protect data in transit.
  </Card>

  <Card title="Monitor Token Expiry" icon="fa-hourglass-end">
    Be aware that ephemeral tokens expire after 24 hours. Implement logic to refresh tokens as needed.
  </Card>

  <Card title="Handle Errors Gracefully" icon="fa-exclamation-triangle">
    Handle errors gracefully, such as when an ephemeral token has expired or if the user does not have the necessary permissions.
  </Card>
</Cards>

## Common Errors and Troubleshooting

<Accordion title="Permission Errors" icon="fa-ban">
  **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.
</Accordion>

<Accordion title="Invalid API Key" icon="fa-key">
  **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.
</Accordion>

<Accordion title="Missing User Parameters for SSO" icon="fa-user-times">
  **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.
</Accordion>

<Accordion title="Token Expiration" icon="fa-clock">
  **Error Message:** "Token has expired."

  **Cause:** The ephemeral token has expired after 24 hours.

  **Solution:** Generate a new ephemeral token using your API Key.
</Accordion>

## Best Practices

<Cards columns={2}>
  <Card title="Rotate API Keys Regularly" icon="fa-sync-alt">
    Enhance security by rotating your API Keys periodically. Update your server configurations accordingly.
  </Card>

  <Card title="Implement Token Refresh" icon="fa-redo">
    In client applications, implement logic to handle token expiration and request a new ephemeral token when needed.
  </Card>

  <Card title="Limit Token Scope" icon="fa-user-shield">
    Only grant the necessary permissions required for the client application. Avoid unnecessary privileges to reduce security risks.
  </Card>

  <Card title="Monitor API Usage" icon="fa-chart-line">
    Keep track of API usage and monitor for any unusual activity. Set up alerts for failed authentication attempts or other anomalies.
  </Card>
</Cards>