Guides
Learn More about Newline

Authentication Guide

Suggest Edits

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, providing 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.

Authentication Guide Sections:

  1. Introduction to Authentication
  2. Prerequisites
  3. Authentication Workflow
  4. Using the Bearer Token
  5. Trace ID Requirements
  6. Error Handling
  7. Sandbox Authentication
  8. Best Practices

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.api.newline53.com](https://sandbox.api.newline53.com/)
    • Production: [https://api.newline53.com](https://api.newline53.com/)

3. Authentication Workflow

The authentication workflow involves three key steps:

  1. Token Generation: Use the Program UID and HMAC Key to generate a signed token.
  2. Sending the Token: Send the signed token to the /auth/token endpoint to obtain a Bearer token.
  3. Token Expiration: Monitor the Bearer token’s expiration and refresh it as needed.

Step 1: Token Generation

  • Use the Program UID and HMAC Key with a predefined algorithm (HS512 / SHA-512) to create a signed token.

Step 2: Sending the Token

  • Send the signed token to the Authentication Endpoint /auth/token to receive a Bearer token.

    Example API Call:

    curl -X POST [https://sandbox.api.newline53.com/auth/token](https://sandbox.api.newline53.com/auth/token) \ -H "Content-Type: application/json" \ -d '{ "program_uid": "YOUR_PROGRAM_UID", "signature": "GENERATED_SIGNATURE" }'

Step 3: Token Expiration

  • Once expired, the token cannot be used and must be regenerated.

4. Using the Bearer Token

To use the Bearer token for authenticating API requests, follow these three steps:

  1. Receive the Bearer Token: Generate the token via the /auth/token endpoint.
  2. Include the Token in API Requests: Use the Authorization header with the token.
  3. Handle Expiration: Ensure tokens are refreshed before they expire.

Header Example:

plaintext

Copy code

Authorization: Bearer YOUR_BEARER_TOKEN

Example API Call:

`curl -X GET [https://sandbox.api.newline53.com/v1/accounts](https://sandbox.api.newline53.com/v1/accounts) \
     -H "Authorization: Bearer YOUR_BEARER_TOKEN"

5. Trace ID Requirements

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

  1. Generate a Unique Trace ID: Create a unique ID 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 avoid API errors.

Example with Trace ID:

curl -X GET <https://sandbox.api.newline53.com/v1/accounts>   
     -H "Authorization: Bearer YOUR_BEARER_TOKEN"   
     -H "X-Trace-ID: UNIQUE_TRACE_ID"

6. Error Handling

Proper error handling requires three 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 three main steps:

  1. Authenticate Using Sandbox URL: Generate a token via the /auth/token 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 four 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 8 days ago