About UsStatus Page
Developer API
Start typing to search…

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:

Enhanced Security: Keep your long-term API Key secure on your server.

Temporary Access: Tokens expire after 24 hours, reducing the risk if compromised.

Flexibility: Use tokens for mobile SDKs or to enable Single Sign-On (SSO) for sub-merchants.

Use Cases

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.

Single Sign-On (SSO) for Sub-Merchants:

Enable SSO for sub-merchants by generating an ephemeral token with specific URL query parameters. Allows sub-merchants to access the Stax platform seamlessly through your application.

Implementing Ephemeral Tokens

  1. Generate an API 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.
  2. Make a Request to Generate an Ephemeral Token:
    1. Without URL Parameters:
      1. Suitable for server-to-server communications where you are acting as your own user.
      2. Not recommended for SSO or client-side usage.
    2. With URL Parameters (user_id or user_email):
      1. Use when you need to authenticate on behalf of a specific user, such as in mobile apps or for SSO.
      2. Include the user_id or user_email in the URL parameters.
  3. Use the Ephemeral Token:
    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: 
      1. Authorization: Bearer EPHEMERAL_TOKEN
  4. Implement SSO (If Applicable):
    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.

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.

Prerequisites

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.

Request SSO into Stax

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.
  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
  1. Build the Full SSO URL


Security Recommendations

Do Not Expose API Keys:

  • Never expose your long-term API Key to clients, browsers, or mobile applications.
  • Always keep API Keys secured on your server.

Use HTTPS:

  • Ensure all API calls are made over HTTPS to protect data in transit.

Token Expiry:

  • Be aware that ephemeral tokens expire after 24 hours.
  • Implement logic to refresh tokens as needed.

Error Handling:

  • Handle errors gracefully, such as when an ephemeral token has expired or if the user does not have the necessary permissions.

Common Errors and Troubleshooting

Permission Errors:

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.

Invalid API 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.

Missing User Parameters for SSO:

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.

Token Expiration:

Error Message: "Token has expired." Cause: The ephemeral token has expired after 24 hours. Solution: Generate a new ephemeral token using your API Key.

Best Practices

Rotate API Keys Regularly:

  • Enhance security by rotating your API Keys periodically.
  • Update your server configurations accordingly.

Implement Token Refresh Mechanism:

  • In client applications, implement logic to handle token expiration and request a new ephemeral token when needed.

Limit Token Scope:

  • Only grant the necessary permissions required for the client application.
  • Avoid unnecessary privileges to reduce security risks.

Monitor API Usage:

  • Keep track of API usage and monitor for any unusual activity.
  • Set up alerts for failed authentication attempts or other anomalies.