# Authenticate

Generate OAuth bearer tokens and authenticate requests to Deluxe APIs.

Deluxe APIs use the OAuth 2.0 Client Credentials flow.

Before calling any API, generate a bearer token using your Client ID and Client Secret. Include the bearer token and merchant Access Token with every API request.

### Authentication Flow

The authentication flow shows how to obtain a Bearer Token using a Client ID and Client Secret, then use the Bearer Token and Merchant Access Token to make an authenticated API request.

**Request OAuth Token**
Use the Client ID and Client Secret to request an OAuth Bearer Token before calling an API.

**Receive Bearer Token**
The OAuth token request returns the Bearer Token required for authentication.

**Create API Request**
Create the API request using the required authentication credentials.

**Add Authorization Header**
Include the Bearer Token in the Authorization header.

**Add partnerToken Header**
Include the Merchant Access Token in the `partnerToken` header.

**Make Authenticated API Call**
Send the API request with both authentication headers to make the authenticated API call.

### Request a Bearer Token

Obtain a bearer token by sending an OAuth token request using your Client ID and Client Secret.

```http
POST https://sandbox.api.deluxe.com/secservices/oauth2/v2/token

Authorization: Basic <base64(ClientID:ClientSecret)>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
```

The `Authorization` value is your Client ID and Client Secret joined with a colon (`:`) and Base64-encoded.

### Sample Response

```json
{
  "access_token": "eyJhbGciOi...",
  "tokenExpiry_time": "...",
  "expires_in": 3300
}
```

The `expires_in` value is returned in seconds.

```text
3300 seconds = 55 minutes
```

### Send Authenticated Requests

Include both headers on every API request:

```http
Authorization: Bearer <access_token>
partnerToken: <Access Token GUID>
```

Optionally include a `requestId` header:

```http
requestId: <GUID>
```

The `requestId` value is echoed back in the response and can be used for tracing, diagnostics, and support activities.

### Verify Your Access

After obtaining credentials and generating a bearer token, verify your access by submitting a test payment in Sandbox.

```http
POST https://sandbox.api.deluxe.com/dpp/v1/payments

Authorization: Bearer <access_token>
partnerToken: <Access Token GUID>
Content-Type: application/json
```

**Example Request**

```json
{
  "paymentType": "Sale",
  "amount": {
    "amount": 1.00,
    "currency": "USD"
  },
  "paymentMethod": {
    "card": {
      "card": "4005519200000004",
      "expiry": "12/30",
      "cvv": "123"
    },
    "billingAddress": {
      "firstName": "Test",
      "lastName": "User",
      "address": "123 Main St",
      "city": "Dallas",
      "state": "TX",
      "postalCode": "75001",
      "country": "US"
    }
  }
}
```

A successful response confirms that:

- Authentication is configured correctly.
- The bearer token is valid.
- The `partnerToken` is valid.
- API connectivity has been established.
- Requests can be processed successfully.


A successful response returns:

- `responseCode: 0`
- `authResponse: 123456` (all approval test cards return this authorization code)
- `paymentId`, a GUID identifying the transaction


### Token Management

Follow these recommendations when managing OAuth tokens:

- Generate bearer tokens server-side only.
- Store the Client ID and Client Secret securely.
- Refresh bearer tokens before they expire.
- Use automated token renewal whenever possible.
- If a request returns `401 Unauthorized`, generate a new bearer token and retry the request once.


### Base Path

Use `/dpp/v1` for all new integrations.

`/dpp/v1/gateway` is a legacy path and is maintained for backward compatibility.

### Authentication Checklist

- Client ID and Client Secret have been received.
- OAuth bearer token can be generated successfully.
- Authorization header is included on API requests.
- partnerToken header is included on API requests.
- Token refresh logic is implemented.
- Application successfully authenticates against the Sandbox environment.


### Next Steps

Developer Guide
Request Sandbox access, obtain credentials, and prepare your development environment.

Postman Collection
Test authentication and API requests using the Deluxe Postman collection.

Payments API
Create and manage payment transactions using authenticated API requests.