Authentication Guide

Introduction

In order to prevent unauthorized calls to our API, our endpoints are secured with authentication tokens. This guide will walk you through setting up your application with the required authentication for secure API access. By the end of this guide, you'll be able to authenticate and make your first API calls.

Prerequisites

• Basic understanding of REST APIs.
• Familiarity with JSON.
• Access to the clientId and clientSecret provided by our team.
• Partner ID partnerId provided by our team.

Setting Up Your Application

1. Register Your Application: You'll receive from us, a clientId and clientSecret, which are essential for authentication.
2. Store Credentials Securely: Store these credentials in a secure but accessible manner within your application.

Obtaining Access Tokens

1. Encode Your Credentials: Use Base64 URL encoding to encode clientId:clientSecret. This encoded string is used in the authorization header.

   echo -n 'clientId:clientSecret' | base64

2. Request an Access Token: Perform a POST request to the Amazon Cognito token endpoint with your encoded credentials.

   curl -v -X POST -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Basic {encoded_credentials}' "https://ps.auth.eu-central-1.amazoncognito.com/oauth2/token?grant_type=client_credentials"

   Replace {encoded_credentials} with your encoded string.

3. Handle the Token Response: Store the access_token and refresh_token received. By default, access and ID tokens expire after 1 hour, but Cognito User Pools also issue a refresh token, which expires after 30 days by default.

Refreshing Expired Tokens

For tokens obtained via the client_credentials grant, Amazon Cognito does not issue refresh tokens due to the nature of the client credentials flow, which is intended for server-to-server communication without user interaction.

To obtain a new access token after the current one expires, you should repeat the initial token request process using its clientId and clientSecret. This is securely handled server-side, ensuring your application maintains continuous access to the API without manual intervention.

Making Your First API Call

1. Use the Access Token: Include the access_token in the Authorization header as a Bearer token.

   curl -v -X POST -H 'Authorization: Bearer {access_token}' -H 'Content-Type: application/json' -d '{"userId": "userXYZ789", "productId": "productABC456", "purchaseRef": "AcmeCorp123-refDEF123"}' https://dealer-api.axelspringer.com/partners/{partnerId}/purchase

   Replace {access_token} with your actual token.

Troubleshooting

• Invalid Credentials: Ensure your clientId and clientSecret are correctly encoded and valid.
• Expired Token: Tokens have an expiration period. Implement a method to refresh the token using the refresh_token when necessary.

Example

For documentation purposes, here is an example with typescript and using the Fetch API to obtain an access token and make an API call.

This is not a complete example, but should give you an idea of how to implement the authentication process.

import * as base64 from "base-64";

// Replace with your clientId and clientSecret
const clientId = "yourClientId";
const clientSecret = "yourClientSecret";

// Encode your credentials
const encodedCredentials = base64.encode(`${clientId}:${clientSecret}`);

// Function to obtain an access token
const getAccessToken = async () => {
  const tokenEndpoint =
    "https://ps.auth.eu-central-1.amazoncognito.com/oauth2/token";
  const response = await fetch(tokenEndpoint, {
    method: "POST",
    headers: {
      Authorization: `Basic ${encodedCredentials}`,
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: "grant_type=client_credentials",
  });

  if (!response.ok) {
    throw new Error("Failed to obtain access token");
  }

  const data = await response.json();
  return data.access_token;
};

// Function to make an API call
const makeApiCall = async (accessToken: string) => {
  const apiUrl = `https://dealer-api.axelspringer.com/partners/{partnerId}/purchase`;
  const response = await fetch(apiUrl, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      userId: "userXYZ789",
      productId: "productABC456",
      purchaseRef: "AcmeCorp123-refDEF123",
    }),
  });

  if (!response.ok) {
    throw new Error("API call failed");
  }

  return await response.json();
};

// Usage
(async () => {
  try {
    const accessToken = await getAccessToken();
    const result = await makeApiCall(accessToken);
    console.log("API Call Result:", result);
  } catch (error) {
    console.error("Error:", error);
  }
})();

Support

For additional guidance or support, please refer to our Developer Guides or contact our Support Team.