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 must access the report within 72 hours. After this period, a RELAY_TOKEN_EXPIRED error message will be returned to the third party when they attempt to access the report. You can refresh a relay token expiration by calling the POST /relay-tokens endpoint using the same publicId and publicToken originally used to generate the relay token, this will give the third party another 72 hours to access the report.

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.

Possible responses‍‍

• 200 (OK) The newly generated relayToken is returned. This is a UUID that the third party can use to access the report associated with the provided publicToken.
• 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"
}'

Example response

{
	"relayToken": "fbab54b4-8c7f-436b-9539-b5f660401bf8"
}

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.

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

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.