Onboarding

How to Get Access Tokens with Client Credentials

by dev-portal-admin |

As all USCIS Torch API’s are secured with OAuth 2.0 Security authentication, it is important to understand the AuthN + AuthZ handshake to occurs as you participate with the API’s and their flows built on the Torch Platform. Client Credentials play a vital role in identifying your client app and are issued at the time you create a new Developer App on the platform. Your Developer App will be assigned two keys: the Consumer ID and the Consumer Secret.

  • Consumer ID: (or Consumer Key): is a public key
  • Consumer Secret: must never be made public

Your Client Credential Pair is used to pass an Authentication Request to Torch API, and if the pairing is authenticated – Torch API will send an Access Token, completing the authentication.

Once you have secured your authentication, you are now enabled to authenticate API calls with your Access Token towards the resource server, to request data.

Authentication Flow

How do I get my Client ID and Client Secret?

 Client Credentials are issued through the Developer App creation. For detailed instructions on completing this, you can view How to create an App KBA. You can complete this in a few simple steps.

  1. Login/Signup at https://developer.uscis.gov/
  2. Click on Apps in the Upper Right Menu
  3. Click on Add App
  4. Provide:
    1. App Name: This can be anything
    2. Callback URL: This is optional unless using three-legged OAuth.
    3. Description: Tell us about your App and their main functions
    4. Select API Products: Tell us which APIs you would like to have access to, for this Application. (can be >1)
  5. Add App

Completion of your Developer App will issue your Client Credentials. To access your Client ID and Client Secret, click on the App Name > Scroll to the Credentials Section > and Toggle the Eye Icon next to your keys to view.

Client Credentials

 

Managing Client Credentials

Client Credentials can be managed from within the Developer Portal only. Once your Developer App is created, you can:

  • Issue additional Client Credentials to an existing app
  • Revoke a Client Credentials from an existing app

Issue Additional Client Credentials

From the App Overview Screen > Click on Add Key

Managing Client Credentials

Select your Expiration preference:

Client Credentials Expiration Settings
  • Never: Keys are only invalid if you manually revoke
  • Date: Keys will expire on selected date at 12:00 AM EST

Revoke Client Credentials

To revoke a pair of Client Credentials, you must always have at least 2 or more set of Client Credentials Issued. The App will always require at least 1 pair of Approved & Active Credentials.

If you have Client Credentials Eligible for revocation, a grey button will appear in the upper right hand corned. Please tread with caution as this process is irreversible. If you need to re-issue revoked keys, you must issue a new set.

Revoke Client Credentials

 

Getting your Access Tokens

With your Client Credentials, you can make a request to the OAuth 2.0 Access Token URL (Authentication Server). You can locate the OAuth 2.0 URLS Below:

Sandbox Environment:

Production Environment:

  • Currently Unavailable

 

Using CURL to get your Access Token

Sample Curl:

 curl --request POST \
  --url 'https://api-int.uscis.gov/oauth/accesstoken' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'client_id=XXXXXXXXXXXXXXXXX' \
  --data client_secret=XXXXXXXXXXXXXX

Sample Response:

{
  "refresh_token_expires_in" : "0",
  "api_product_list" : "[test-case-status-api-usda-stage, csol-api-usda-int, OAuth-Int]",
  "api_product_list_json" : [ "test-case-status-api-usda-stage", "csol-api-usda-int", "OAuth-Int" ],
  "organization_name" : "uscis",
  "developer.email" : "test@email.com",
  "token_type" : "BearerToken",
  "issued_at" : "1583340648488",
  "client_id" : "<client_id>",
  "access_token" : "<access_token>",
  "application_name" : "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
  "scope" : "",
  "expires_in" : "1799",
  "refresh_count" : "0",
  "status" : "approved"
}

 

What You Should Know

OAuth Access Tokens Expire every 30 mins

Through the Client Credential authorization, an Access Token is granted via OAuth 2.0. The Access Token is used to authenticate your API calls towards the resource server, when requesting data from that API Endpoint. Tokens expire every 30 minutes. When you receive your access token, you'll also receive a timestamp of when that token is going to expire. We recommend using coding and logic to call the OAuth Token again to refresh your token manually.

Example Output from OAuth 2.0 Authentication Endpoint

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[TestAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "test@email.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

If you encounter an expired Access Token Error it is very important to notify us. There may be an issue with the Client Credential + Access Token Combination, or a failure to refresh your Access Tokens.

Please contact developersupport@uscis.dhs.gov for any questions.

 

Use of Separate Apps for Sandbox and Production Environments

Currently Torch API’s are available in Sandbox only. Production environments are TBD.

When Production environments are available, you can use the same user account used for Sandbox, for your Production instance (some restrictions may apply at provisioning).

To “separate” your environments, we suggest creating a Developer App per environment.