logo

Authentication

Getting Access to Extend API Resources

DailyPay adheres to the OAuth 2.0 RFC 6749 specification. This document will walk you through the steps to get an authorization_code after a user consents, which can then be exchanged for an access token and refresh token so that your application can make requests to the Extend API.

Depending on your use case, you can use one of the following authentication methods:

  • Authorization Code Grant: This method is suitable when access to resources requires user consent, such as bank account information or the ability to initiate transfers on behalf of the user.

    It allows your application to get access and refresh tokens, facilitating user consent and enabling your application to perform actions on their behalf. For example, to call the User endpoints.

  • Client Credential Flow: This method is employed when access to pre-arranged resources, such as employer(s) and their eligible employees, is required.

    The client credentials grant facilitates the acquisition of an access token independent of a user's protected resources. For instance, you can utilize the Organizations endpoint.

Prerequisite:

You must contact your DailyPay representative to receive a client id and secret for authentication.

Authorization Code Grant:

Request User Authorization & DailyPay Access Token

1. Request User Authorization

To access the Extend API using OAuth 2.0, follow these initial steps:

Prerequisites & purpose:

The purpose of following the OAuth2 flow is to help you generate and retrieve an authorization_code that you can later use to get an access_token via the Request access token endpoint and start making more Extend API calls.

Before proceeding, DailyPay generates a set of client credentials that consist of the following parameters:

  • client_id, secret, scope (provided by DailyPay)
  • redirect_uri (provided by partner)
Example parameters and how to use them:
  • scope: For example, user:read_write
    • Make sure to substitute the : with %3a when updating the /authorize endpoint URL.
    • i.e. user%3aread_write
  • client_id: An ID representing the client directing the current user to the OAuth authorization code flow
  • redirect_uri: A URL of your choice, which must match the URL added at the point of the client credential generation by DailyPay.
    • Once you grant/allow access in the OAuth flow, the browser will be redirected back to your state's redirect_uri either successfully with a code parameter in the address bar, or failed with an error code.
    • In cases whereby an error code is returned, please refer to our Troubleshooting steps.

OAuth flow:

To initiate the OAuth2 authorization process, navigate to the /authorize endpoint below, and replace the {scope}, {client_id}, and {redirect_uri} parameters accordingly. Ensure that they match the values provided during client credential generation.

https://api.dailypay.com/oauth/authorize?response_type=code&scope={scope}&client_id={client_id}&redirect_uri={redirect_uri}
Example for reference: 
https://api.dailypay.com/oauth/authorize?response_type=code&scope=user%3aread_write&client_id=insertClientIdHere&redirect_uri=https://redirect_example.com


From there, you will be prompted to log in or create a new DailyPay account and Allow access to get your authorization_code. (See flow visual below)


What to do with the authorization_code:

Once you get the authorization_code, you can utilize it to request an access_token (see “2. Request a DailyPay Access Token” below).

This enables your application to make requests to the Extend API on behalf of a user. For example, to Get user details or Get a transfer account.

2. Request a DailyPay Access Token

Prerequisites

  • Your code from the previous user authorization and consent in the section above.

Requesting an Access Token

As also specified in our [Request access token guide](Authentication#operation/requestOauthAccessToken), a request for an access token requires you to send the following parameters in the request body.

Parameter Required Description
grant_type Yes Must be set to authorization_code.
client_id Yes The client identifier is required unless passed in the header of the request, see note below.
code Yes The authorization code received from the authorization server.
redirect_uri Yes If included, MUST be the redirection URI used in the initial authorization request.

Example Request to the DailyPay OAuth Endpoint

curl --request POST \
    --url https://api.dailypayuat.com/v1/authorization/oauth/token \
    --header 'accept: application/json' \
    --header 'authorization: Basic Q2xpZW50X1VkZ3NkZm...' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data "grant_type=authorization_code"
    --data "code=AUTHORIZATION_CODE"
    --data "redirect_uri=example.com"

Example 200 Response which contains an access

Client Credential Flow:

Parameters & Example request
  • Client credentials are preferred to access confidential information that a client agrees upon with DailyPay ahead of time.

Parameters

Parameter Required Description
grant_type Yes Must be set to client_credentials.
client_id Yes The client identifier assigned by your DailyPay representative. Required if not passed in the authentication header.

Example Client Credentials Request

curl --request POST \
    --url https://api.dailypayuat.com/v1/authorization/oauth/token \
    --header 'accept: application/json' \
    --header 'authorization basic: Q2xpZW50X1VkZ3NkZm...' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data "grant_type=client_credentials"

Example 200 response with an access token

  • This resulting access token can be used to make requests to the Extend API
{
    "access_token": "dpo_38347Ae178B4a16C7e42F292c6912E7710c8",
    "token_type": "bearer",
    "expires_in": 3600,
    "created_at": 1669741580
}

Additional Token Information

Token Size

  • The authorization code, access token, and refresh tokens can vary in size but will typically remain under 4096 btyes.

Token Introspection Operation

Revoke a Token Operation

SSO and OAuth

  • If you are interested in SSO, please speak with your DailyPay representative to learn more.
  • DailyPay supports Single Sign-On (SSO) at employers and is enabled on a client-by-client basis.

Request access token

Request a Dailypay user access token, as described in the OAuth2 spec. When grant_type is authorization_code, the authorization_code and redirect_uri parameters are required. When grant_type is refresh_token, the refresh_token parameter is required.

SecurityclientBasicAuth
Request
Request Body schema: application/x-www-form-urlencoded
required
code
string

An authorization code received through user authorization flow.
(Required when grant_type is authorization_code, otherwise remove it)

Example: "50BTIf2h7Wtg3DAk7ytpG5ML_PsNjfQA4M7iupH_3jw"
grant_type
required
string

The OAuth grant type.

Enum: "authorization_code" "refresh_token"
Example: "authorization_code"
redirect_uri
string

The url redirected to after authorization flow was completed by current user. Only used in authorization code grant flow.

Example: "https://example_redirect.com"
refresh_token
string

A refresh token received previously from /token endpoint.
(Required when grant_type is refresh_token, otherwise remove it)

Example: "refresh_token"
Responses
200

DailyPay user access token.

400

Server cannot process the request due to client error

500

Server experienced an unknown or unexpected error.

post/authorization/oauth/token
Request samples
application/x-www-form-urlencoded
grant_type=authorization_code&refresh_token=refresh_token&code=50BTIf2h7Wtg3DAk7ytpG5ML_PsNjfQA4M7iupH_3jw&redirect_uri=https%3A%2F%2Fexample_redirect.com
Response samples
application/json
{
  • "access_token": "dpo_38347Ae178B4a16C7e42F292c6912E7710c8",
  • "refresh_token": "dpo_38347Ae178B4a16C7e42F292c6912E7710c9",
  • "token_type": "bearer",
  • "expires_in": 3600,
  • "created_at": 1669741580
}

Introspect access token

Takes an access token or refresh token and returns a boolean that indicates whether it is active, as described in the OAuth 2.0 Token Introspection spec. If the token is active, additional data about the token is also returned. If the token is invalid, expired, or revoked, it is considered inactive.

Note that the following optional fields in the Token Introspection spec are not implemented: username, nbf, sub, aud, iss, jti

SecurityclientBasicAuth
Request
header Parameters
Authorization
string

Encoded client_uid and secret separated by colon.

Example: Basic {credentials}
Request Body schema: application/x-www-form-urlencoded
required
token
required
string

the access token or refresh token to revoke

Example: "LjSfXMXSvDth2ZqnmsFzZwrye7ubeHddlOxFRr6-nis"
token_type_hint
string

A hint of the type of token

Enum: "access_token" "refresh_token"
Example: "access_token"
Responses
200

Successful introspection

400

Server cannot process the request due to client error

401

Indicates that the request is not authorized

post/authorization/oauth/introspect
Request samples
application/x-www-form-urlencoded
token=LjSfXMXSvDth2ZqnmsFzZwrye7ubeHddlOxFRr6-nis&token_type_hint=access_token
Response samples
application/json
{
  • "active": true,
  • "scope": "read read_write",
  • "client_id": "a9VpZDRCeFh3Nkk2VdYa32",
  • "token_type": "Bearer",
  • "exp": 1679327408,
  • "iat": 1679327408
}

Revoke token

The API takes an access or refresh token and revokes it, as described in the OAuth 2.0 Token Revocation spec. Revoked tokens are considered inactive at the introspection endpoint. A client may only revoke its own tokens.

SecurityclientBasicAuth
Request
header Parameters
Authorization
string

Encoded client_uid and secret separated by colon. Required for revoking tokens issued from the client_credentials grant type

Example: Basic {credentials}
Request Body schema: application/x-www-form-urlencoded
required
token
required
string

the access token or refresh token to revoke

Example: "LjSfXMXSvDth2ZqnmsFzZwrye7ubeHddlOxFRr6-nis"
token_type_hint
string

A hint of the type of token

Enum: "access_token" "refresh_token"
Example: "access_token"
Responses
200

Indicates that the token has been revoked successfully or the client submitted an invalid token

401

Indicates that the request is not authorized to revoke the given token

post/authorization/oauth/revoke
Request samples
application/x-www-form-urlencoded
token=LjSfXMXSvDth2ZqnmsFzZwrye7ubeHddlOxFRr6-nis&token_type_hint=access_token
Response samples
application/json
{
  • "error": "unauthorized_grant",
  • "error_description": "You are not authorized to revoke this token"
}
➔ Next to Users