Relay Token Quickstart Guide

Nova Credit provides a "Relay Token" feature that allows customers to efficiently share reports with third parties. To utilize this feature, third parties must be registered as Nova Credit customers.

This document provides information on how to interact with the Nova Credit API to grant and revoke third party access to reports. For more general information about the Nova Credit APIs, view your corresponding quickstart guide (Credit Passport Quickstart, Income Navigator Quickstart, Cash Atlas Quickstart).

Where to configure Relay Token

To enable and configure Relay Token functionality, please contact your Nova Credit representative. Our support team will assist you in setting up the necessary configurations to use this functionality.

Credentials & Identifiers

Account Keys

The NovaConnect and server-side API keys are accessible from your Nova Credit Dashboard.

• publicId [string] Used to identify your account or that of a third party.
• clientId [string] Your Nova Credit API identifier. You will use this to programmatically access resources.
• secretKey [string] Your Nova Credit API key (keep this secret). You will use this to programmatically access resources.

Programmatically generated tokens

• publicToken [string] Identifies a specific report.
• relayToken [string] Identifies a report generated from another report's data for sharing with a third party. A relayToken is a publicToken.
• accessToken [string] Used to authorize server-side requests (keep this secret). You will generate an accessToken each time you fetch a report.

Grant a third party access to a report

The following instructions apply after an applicant has completed NovaConnect and a report has been generated.

To grant a third party access to a report, you need to generate a relay token using the POST https://api.novacredit.com/connect/relay-tokens endpoint.

You can only generate relay tokens within 30 days from the date the initial report is created. After this period, relay token generation will be disallowed and the POST /relay-tokens endpoint will return a RELAY_TOKEN_EXPIRED error message.

Once a relay token is generated, the third party has 72 hours to access the report. After 72 hours, requests made with that relay token return a RELAY_TOKEN_EXPIRED error.

To give the third party another 72 hours, call POST /relay-tokens again with the same publicId and publicToken used to generate the relay token.

Note: userArgs are set when the relay token is first generated and stay fixed for that publicId and publicToken combination. If you extend access and include userArgs that differ from the originals, the request still succeeds and the expiration is extended, but the new userArgs are ignored. The report continues to return the original userArgs.

Required headers‍

• Authorization Basic Auth, containing the base-64 encoded string of your clientId:secretKey.
• Content-Type application/json.

‍Required body parameters

• publicToken [string] Unique UUID of the report you want to grant access to.
• publicId [string] Public ID of the third party that will be granted access to the report associated with the publicToken provided.

Optional body parameters

• userArgs [string] Pass in an identifier for your own records. It will be provided in our webhook call if specified in the callback and in the API JSON response. Max length 255 characters.

Possible responses‍‍

• 200 (OK) The relayToken is returned. This is a UUID that the third party can use to access the report associated with the provided publicToken. If a userArgs value is stored on the relay token, it is returned in the userArgs field.
• 400 (Bad Request) Malformed or invalid request, headers or missing required parameters. Error will be one of INVALID_PARAMETERS, MALFORMED_BODY, MALFORMED_HEADERS, INVALID_PUBLIC_ID, RELAY_TOKEN_EXPIRED, RELAY_TOKEN_REVOKED.
• 403 (Forbidden) Unauthorized request. Your clientId or secretKey was incorrect, or you did not correctly base-64 encode it.
• 404 (Not Found) No report was found with the publicToken provided.

Example request

curl --location --request POST 'https://api.novacredit.com/connect/relay-tokens' \
--header 'Authorization: Basic {Token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "publicId": "7292265cd901306dd78e13e8c09ec269c872ad863aff6c15af9799d9de6c02ds",
    "publicToken": "7b8a098a-f529-4612-a8ae-dbcef388e634",
    "userArgs": "application-id-12345"
}'

Example response

{
	"relayToken": "fbab54b4-8c7f-436b-9539-b5f660401bf8",
	"userArgs": "application-id-12345"
}

application json

Revoke a third party access to a report

To revoke a third party access to a report, you need to revoke the corresponding relay token using the DELETE https://api.novacredit.com/connect/relay-tokens/:relayToken endpoint.

If relayToken provided to the DELETE /relay-tokens endpoint is already revoked, the endpoint will return a RELAY_TOKEN_REVOKED error message. Otherwise, the endpoint will return a successful response even if the relay token has already expired.

Upon revocation, relay token generation will be disallowed for the publicId and publicToken combination used to generate the revoked relay token. In other words, any attempt to call the POST /relay-tokens endpoint with that combination will result in a RELAY_TOKEN_REVOKED error message.

Required headers‍

• Authorization Basic Auth, containing the base-64 encoded string of your clientId:secretKey.

‍Required path parameters

• relayToken [string] Relay token to revoke.

Possible responses‍‍

• 200 (OK) Relay token revoked successfully.
• 400 (Bad Request) Malformed request or headers. Error will be one of MALFORMED_HEADERS, RELAY_TOKEN_REVOKED.
• 403 (Forbidden) Unauthorized request. Your clientId or secretKey was incorrect, or you did not correctly base-64 encode it.
• 404 (Not Found) Relay token not found.

Example request

curl --location --request DELETE 'https://api.novacredit.com/connect/relay-tokens/51414543-b761-40ae-8cfa-34639af20c5c' \
--header 'Authorization: Basic {Token}'

Relay token guide for third parties

For a third party to access a report using a relay token, they need to:

1. Obtain the relay token
2. Verify the report associated with the relay token is ready to be retrieved
3. Retrieve the report

How a third party can obtain a relay token and verify the report is ready to be retrieved

There are two options for a third party to obtain a relay token and verify the associated report is ready to be retrieved.

** Recommended option: using webhooks **

All created relay tokens will result in a VISIT SUCCESS webhook call to the third party. The webhook payload will contain the relay token in the publicToken field, and is an indication that the report is ready to be retrieved. If a userArgs value was provided when the relay token was created, it is included in the webhook payload's userArgs field.

This means that if the third party is already subscribed to webhooks, then they will automatically begin receiving calls for the created relay tokens.

More information regarding the webhook body can be found in API docs:

• Cash Atlas API Docs - Webhooks
• Income Navigator API Docs - Webhooks

** Alternative option: using the /status endpoint **

If the third party is not subscribed to webhooks, you will need to pass the relay token provided by the POST /relay-tokens endpoint to the third party.

Then, the third party should get an access token and finally poll the status of the report associated with the relay token until the status is SUCCESS which indicates the report is ready to be retrieved.

How a third party can retrieve a report using a relay token

Once the third party has obtained the generated relay token and verified the report is ready to be retrieved, they will use the standard method to retrieve the report but using the relay token as the publicToken (also known as X-PUBLIC-TOKEN header) in API calls.

More information can be found in quickstart guides:

• Cash Atlas Quickstart Guide - Server Side Integration
• Income Navigator Quickstart Guide - Server Side Integration

How to get an access token

To make a request to Nova Credit's servers to get the status of a report or retrieve a report, you will need to first fetch an access token using your Nova Credit client id and secret key. Access tokens are time-scoped to prevent malicious usage should someone obtain one. You should retrieve a new access token each time you intend to retrieve a report.

GET https://api.novacredit.com/connect/accesstoken

Required headers

• Authorization Basic Auth, containing the strict base-64 encoded string of your clientId:secretKey (ensure you use the corresponding client id and secret key to the environment you define).

Possible responses‍‍

• 200 (OK) Both accessToken and exp will be returned.
• 403 (Forbidden) Unauthorized request. Your clientId or secretKey was incorrect, or you did not correctly base-64 encode it.
• 400 (Bad Request) Malformed request, headers or missing required parameters. Error will be one of MALFORMED_HEADERS or MALFORMED_BODY.

The response body will be a JSON containing the following keys:

• accessToken The access token you can now use to retrieve a report with.
• exp When the access token will expire, provided as a unix timestamp. Access tokens have a lifetime of 5 minutes. If you do not retrieve the report before the access token expires, you will need to request a new access token.

Example request

curl --location --request GET 'https://api.novacredit.com/connect/accesstoken' \
--header 'Authorization: Basic {Token}'

Example response

{
	"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjMyNTQwNjksImV4cCI6MTcyMzI1NDM2OSwiY2xpZW50X2lkIjoiNjFhNDdiMDQtZWIyMy00YWNlLWE2OWQtYzg4OWI5YjExYTRjIiwiZW52Ijoic2FuZGJveCJ9.HVlHgidZdi2-qY92zhE-MmLYNNqnuIBAoRapA6rbM78",
	"exp": 1526077901
}

How to get the status of a report

The following endpoint can be used to get the status of a report.

GET https://api.novacredit.com/connect/status

Required headers

• Authorization Bearer Auth, containing the strict base-64 encoded string of the valid accessToken you retrieved from the GET /accesstoken endpoint.
• X-PUBLIC-TOKEN The relay token of the report you want to get the status of.

Possible responses‍‍

• 200 (OK) The status of the report will be returned.
• 403 (Forbidden) Unauthorized request. Your accessToken was incorrect, or you did not correctly base-64 encode it.
• 400 (Bad Request) Malformed request, headers or missing required parameters. Error will be one of MALFORMED_HEADERS, MALFORMED_BODY or INVALID_TOKEN.

The response body will be a JSON containing the following keys:

• status The status of the report associated with the provided relay token.

Example request

curl --location --request GET 'https://api.novacredit.com/connect/status' \
--header 'X-PUBLIC-TOKEN: fbab54b4-8c7f-436b-9539-b5f660401bf8' \
--header 'Authorization: Bearer {base64EncodedAccessToken}'

Example response

{
	"status": "SUCCESS"
}

Relevant links

• Cash Atlas Quickstart Guide
• Cash Atlas API Docs
• Income Navigator Quickstart Guide
• Income Navigator API Docs

Changelog

October 2026

• Added an optional userArgs body parameter to the POST /relay-tokens endpoint. The provided value is returned in the VISIT SUCCESS webhook, the generated report's meta.user_args field, and the endpoint's response. userArgs is fixed when the relay token is first created; any value sent on a subsequent call for the same publicId and publicToken is ignored.

June 2025

• Fixed bug where some endpoints, when returning a non-200 status code, were returning a terminated field as a string instead of a boolean

2025 January

• Updated references to X-ENVIRONMENT headers and added information about the new sandbox URL. Note that this header is backwards compatible, and therefore will still work.