Using Nuclei APIs

Overview 

Nuclei APIs allow developers to request information from Nuclei, including (but not limited to) account information, events, and reconciliation reports. API clients can retrieve data directly from Nuclei, and can use that data to extend the functionality of their own applications. 

Authentication

Nuclei authenticates each HTTP request made to the Nuclei API. Nuclei supports the use of OAuth 2.0 and JWT for authentication. 

Authorization Framework

The OAuth 2.0 authorization framework is a protocol that allows a user to grant a third-party web site or application access to the user's protected resources, without necessarily revealing their long-term credentials or even their identity.

OAuth introduces an authorization layer and separates the role of the client from that of the resource owner. In OAuth, the client requests access to resources controlled by the resource owner and hosted by the resource server and is issued a different set of credentials than those of the resource owner. Instead of using the resource owner's credentials to access protected resources, the client obtains an access token--a string denoting a specific scope, lifetime, and other access attributes. Access tokens are issued to third-party clients by an authorization server with the approval of the resource owner. Then the client uses the access token to access the protected resources hosted by the resource server.

Auth0 is used to generate access tokens for API authorization scenarios, in JSON web token (JWT) format. 

The Client Credentials Flow grant type is used for retrieving the access tokens required for communicating with the Nuclei API. 

This process works as follows:

1. The application authenticates with the Auth0 Authorization Server  

2. The Auth0 Authorization Server validates the Client ID and Client Secret.

3. Auth0 Authorization Server responds with an access token.

4. The application can use the access token to call the Nuclei API on behalf of itself.

5. The Nuclei API responds with requested data.

Obtaining an access token

The token authorization endpoint is available at the following URL:

https://nuclei-prod.us.auth0.com/oauth/token

You must execute a client credentials exchange to obtain an access token for the Nuclei API: 

Example (cURL)

curl --request POST \
--url https://nuclei.us.auth0.com/oauth/token \
--header 'content-type: application/json' \
--data '{"client_id":"CLIENT ID","client_secret":"CLIENT SECRET","audience":"https://api.prod.nuclei.ai/v2","grant_type":"client_credentials"}'

Response

{"access_token":"ACCESS TOKEN","expires_in":86400,"token_type":"Bearer"}

Calling the API

Once you have obtained an access token, you can use the access token to call the Nuclei API: 

Example (cURL)

curl --request GET \
--url https://api.prod.nuclei.ai/v2/me \
--header 'authorization: Bearer $ACCESS_TOKEN'

Response

{
    "customer_name":"Foo, Inc",
    "partner_id":""
}

Pagination

All top-level API resources that have support for bulk fetches via "list" methods return paginated responses. The Nuclei API utilizes token based pagination via use of next_page request and response attributes. 

A response that includes additional pages of results is indicated via a next_page value that contains a string token:  

{
    "count": 231,
    "events": [],
    "next_page": "eyJHU0kyUEsiOiAiQ1VTV"
}

That token can be used to retrieve the next page of results by setting the next_page query parameter on your subsequent request:

GET /v2/events?start_date=2022-07-01&end_date=2022-07-02&next_page=eyJHU0kyUEsiOiAiQ1VTV

A response that includes no further pages of results is indicated via a next_page value of null: 

{
    "count": 231,
    "events": [],
    "next_page": null
}

Resources

Documentation - Nuclei API - Introduction

Documentation - Nuclei API - Changelog

Documentation - Nuclei API - API Endpoints

More Information

For more information on the Nuclei API please contact Nuclei's support team at support@nuclei.ai.