Guides
Learn More about Newline
Start typing to search…

Authentication Guide

1. Introduction to Authentication

Authentication is a critical component of integrating with the Newline API. It ensures that only authorized users and systems can access resources within your Program. Newline uses JSON Web Tokens (JWT) as the primary authentication mechanism for both its Sandbox and production environments, designed to provide a consistent and secure approach across testing and production systems.

This guide outlines the authentication process, including required components, token generation, usage, and best practices for security and error handling.

2. Prerequisites

Before you start using the Newline API, ensure you have the following:

  1. Program UID: Provided by Newline. Used to generate signed tokens.
  2. HMAC Key: Provided by Newline. Used to generate signed tokens.
  3. Base URL:
    • Sandbox: https://sandbox.newline53.com/api/v1
    • Production: https://api.newline53.com/api/v1

3. Authentication Workflow

The authentication workflow involves two key steps:

  1. JWT Generation: Use the Program UID and HMAC Key to generate a signed JWT.
  2. Obtaining the Access Token: Send the signed JWT to the /auth endpoint to obtain an Access Token.

Step 1: JWT Generation

Create a JWT with the following structure:

  • Header: {typ: 'JWT', alg: 'HS512'}
  • Payload: {sub: program_uid, iat: current_epoch_time}

Step 2: Obtaining the Access Token

Send the signed JWT to the Authentication Endpoint /auth to receive an Access Token.

Example API Call:

curl -X POST #{base_url}/auth \
  -H "Authorization: Bearer #{jwt}" \
  -H "Content-Type: application/json" \
  -H "x-trace-id: #{SecureRandom.uuid}"

4. Using the Access Token

🚧

Access Token Expiration: Access Tokens issued by Newline are valid for 8 hours. After expiration, a new token must be obtained by repeating the authentication workflow.

Once an access token is retrieved from the /auth endpoint, use it to authenticate all subsequent API requests via the Authorization header.

  1. Include the Access Token in API Requests: Use the Authorization header with the token.
Authorization: #{access_token}

Example API Call:

curl -X GET #{base_url}/custodial_accounts
-H "Authorization: #{access_token}"
-H "Content-Type: application/json"
-H "x-trace-id: #{SecureRandom.uuid}"
  1. Handle Expiration: Ensure tokens are refreshed before they expire.

Monitor the Access Token expiration time and obtain a new Access Token before it expires by repeating the authentication workflow. If the Access Token expires, you will need to repeat the authentication workflow.

5. Trace ID Requirements

Using the X-Trace-ID header involves these important steps:

  1. Generate a Unique Trace ID: Create a unique identifier for every API request.
  2. Include Trace ID in Headers: Add the X-Trace-ID header to all API calls.
  3. Handle Trace ID Errors: Ensure Trace IDs are unique per request to help avoid API errors.

Example with Trace ID:

curl -X GET #{base_url}/custodial_accounts
-H "Authorization: #{account_token}"
-H "Content-Type: application/json"
-H "x-trace-id: #{SecureRandom.uuid}"

6. Error Handling

Proper error handling requires these key actions:

  1. Understand Common Errors: Familiarize yourself with common authentication errors, such as 401 Unauthorized or 422 Missing Required Fields.
  2. Use Error Codes Reference: Leverage Newline’s detailed Error Codes Reference.
  3. Implement Logging: Log errors and debug responses for faster troubleshooting.
  4. Verification: Ensure that the correct IP address is being used during authentication.

7. Sandbox Authentication

Testing in the sandbox involves these main steps:

  1. Authenticate Using Sandbox URL: Generate a token via the /auth endpoint.
  2. Simulate API Requests: Use test customers, accounts, and synthetic data to validate workflows.
  3. Monitor Testing: Review API responses for accuracy and completeness in the simulated environment.

Sandbox Key Features:

  • Simulated testing environment with no real financial transactions.
  • Same authentication and token processes as production.

8. Best Practices

To ensure secure and effective authentication, follow these best practices:

  1. Secure Token Storage:
    • Use environment variables or secrets managers for storing Program UID, HMAC Key, and tokens.
  2. Monitor Token Expiration:
    • Implement a mechanism to refresh tokens before they expire.
  3. Enable HTTPS:
    • Always use HTTPS to encrypt sensitive data during transmission.
  4. Use Unique Trace IDs:
    • Avoid reusing X-Trace-ID values to prevent duplicate processing errors.

9. Additional Resources

Explore the following resources for further guidance:

  1. Developer Documentation:
  2. Error Codes Reference:
  3. Support Channels:

Updated 17 days ago