Access & Authorization

1. REST API Access: OAuth 2.0 (Client Credentials Grant)

Overview:
For REST API integrations, our platform uses the OAuth 2.0 protocol, specifically the "client credentials" grant type, to authenticate and authorize external systems.

Step-by-Step Flow

1. Provisioning Credentials:

   • When onboarding a new API client (such as a partner or application), we generate a unique client ID and client secret for them.
   • These credentials are securely shared with the client as part of the onboarding process.

2. Requesting an Access Token:

   • To interact with the API, clients must first obtain an access token.

   • They do this by making an HTTP POST request to the following endpoint:

     POST https://api.cardlytics.com/api/v1/idp/oauth2/token
     Content-Type: application/x-www-form-urlencoded
     

   • The request payload must include:

     • client_id: The unique client ID you provided.
     • client_secret: The corresponding client secret.
     • grant_type: This must be set to client_credentials.

     Example payload:

     client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=client_credentials
     

3. Receiving the Access Token:

   • If the credentials are valid, the API will respond with a JSON object containing:

     • access_token: The bearer token to use for authentication.
     • expires_in: The token's validity period in seconds (e.g., 3600 seconds = 1 hour).
     • token_type: Typically "Bearer".

     Example response:

     JSON

     {
       "access_token": "abcdef123456...",
       "expires_in": 3600,
       "token_type": "Bearer"
     }
     

4. Using the Access Token:

   • The client includes the access_token in the Authorization header when making subsequent API requests:

     Authorization: Bearer <access_token>
     

   • The API validates the token, ensuring only authorized clients can access the specified endpoints.

2. SFTP Integration: SSH Key Authentication

Overview:
For SFTP-based integrations, our platform uses secure SSH key authentication, combined with specific username assignments and IP restrictions.

Step-by-Step Flow

1. User Onboarding:

   • During onboarding, we assign each client a specific SFTP username.
   • We generate an SSH key pair (public and private keys).
   • The public SSH key is assigned to the SFTP username and stored on our server
   • The private SSH key is encrypted using the client’s public PGP key and then securely shared with the client
     • Clients provide their public PGP key
     • We encrypt the private SSH key with the provided PGP key before sharing

2. IP Registration:

   • We configure the SFTP server (sftp-ads.cardlytics.com) to only allow connections from a predefined set of allowed client IPs.

3. Authentication and Access:

   • When the client connects, they use:
     • Their assigned username.
     • Their private SSH key.
   • The SFTP server authenticates the connection using the client’s public key and checks if the connecting IP is allowed.

4. Directory Access:

   • Upon successful authentication, the client can access only their authorized account directories.

Summary Table