Authentication

Getting Access to DailyPay Public REST 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 DailyPay Public REST API.

Currently, we support the following Authentication method:

  • 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.

  • 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 DailyPay Public REST 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 DailyPay Public REST 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 DailyPay Public REST 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/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/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 DailyPay Public REST 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 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
grant_type
required
string

The OAuth grant type

Enum: "refresh_token" "authorization_code"
Example: "authorization_code"
refresh_token
string or null

A refresh token received previously from /token endpoint

Example: "LjSfXMXSvDth2ZqnmsFzZwrye7ubeHddlOxFRr6-nis"
code
string or null

An authorization code received through user authorization flow

Example: "50BTIf2h7Wtg3DAk7ytpG5ML_PsNjfQA4M7iupH_3jw"
redirect_uri
string or null

The url redirected to after authorization flow was completed by current user. Exclusively used and required for authorization code grant flow

Example: "https://example.com"
Responses
200

DailyPay user access token

Response Schema: application/json
access_token
string
Example: "dpo_38347Ae178B4a16C7e42F292c6912E7710c8"
refresh_token
string
Example: "dpo_38347Ae178B4a16C7e42F292c6912E7710c9"
token_type
string
Example: "bearer"
scope
Array of strings
Example: ["user:read_write"]
expires_in
integer
Example: 3600
400

Something went wrong when exchanging oauth grant or refresh token for an access token. NOTE: This conforms to the OAuth spec and does not follow the same error pattern as the rest of the API

500

Unexpected error occured

post/oauth/token
Request samples
application/x-www-form-urlencoded
grant_type=authorization_code&refresh_token=LjSfXMXSvDth2ZqnmsFzZwrye7ubeHddlOxFRr6-nis&code=50BTIf2h7Wtg3DAk7ytpG5ML_PsNjfQA4M7iupH_3jw&redirect_uri=https%3A%2F%2Fexample.com
Response samples
application/json
{
  • "access_token": "dpo_38347Ae178B4a16C7e42F292c6912E7710c8",
  • "refresh_token": "dpo_38347Ae178B4a16C7e42F292c6912E7710c9",
  • "token_type": "bearer",
  • "scope": [
    • "user:read_write"
    ],
  • "expires_in": 3600
}

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
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

Response Schema: application/json
active
required
boolean

Indicates whether the token is active or not.

scope
string

A space delimited list of scopes.

Example: "read read_write"
client_id
string

The identifier of the client associated with the token.

Example: "a9VpZDRCeFh3Nkk2VdYa32"
token_type
string

The type of token.

Example: "Bearer"
exp
integer

The expiration time of the token in seconds since January 1, 1970 UTC.

Example: 1679327408
iat
integer

The issuing time of the token in seconds since January 1, 1970 UTC.

Example: 1679327408
400

Server cannot process the request due to client error

401

Indicates that the request is not authorized.

post/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
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/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"
}