How to Get Access Tokens with Client Credentials

by dev-portal-admin | January 17, 2023

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.

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.

Login/Signup at https://developer.uscis.gov/
Click on Apps in the Upper Right Menu
Click on Add App
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)
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.

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

Select your Expiration preference:

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.

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:

https://api-int.uscis.gov/oauth/accesstoken

Production Environment:

Available when you Pass your Demo

Using CURL to get your Access Token

Request and Access Token using Client Credentials Grant Type

Curel Request:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&client_id=######&client_secret=######" https://api-int.uscis.gov/oauth/accesstoken

Response:

{
"refresh_token_expires_in": "0",
"api_product_list": "[Case Status API - Sandbox, first-case-sbox]",
"api_product_list_json": [
"Case Status API - Sandbox",
"first-case-sbox"
],
"organization_name": "uscis",
"developer.email": "test@email.com",
"token_type": "Bearer",
"issued_at": "1720723543834",
"client_id": "######",
"access_token": "######",
"application_name": "######-###-###-###-######",
"scope": "",
"expires_in": "1799",
"refresh_count": "0",
"status": "approved"
}

Using your Access Token towards Resource API

Once you have secured your Access Token, add the Bearer Token to your request headers and make an API call towards the Resource API.

The following example is for Case Status API - Sandbox

curl -X GET -H "Authorization: Bearer xxxxxxxxxx" https://api-int.uscis.gov/case-status/EAC9999103402

Response from Case Status API - Sandbox

{
"case_status" : {
"receiptNumber" : "EAC9999103402",
"formType" : "I-130",
"submittedDate" : "09-05-2023 14:28:46",
"modifiedDate" : "09-05-2023 14:28:46",
"current_case_status_text_en" : "Case Approval Was Affirmed",
"current_case_status_desc_en" : "The approval of your case, Receipt Number EAC9999103402, was affirmed and your case is in final review. You will be notified by mail when we have completed working on your case. If you move, go to <a href=\"https://www.uscis.gov/addresschange\" target=\"_blank\">www.uscis.gov/addresschange</a> to give us your new mailing address.",
"current_case_status_text_es" : "Aprobación De Caso Reafirmada",
"current_case_status_desc_es" : "Se ratific\u00F3 la aprobaci\u00F3n del caso para su N\u00FAmero de Recibo EAC9999103402, y se encuentra en la instancia final de revisi\u00F3n. Se le notificar\u00E1 por correo cuando se hayan tomado todas las medidas en su caso. Si cambia de domicilio, visite <a href=\"https://www.uscis.gov/addresschange\" target=\"_blank\">www.uscis.gov/addresschange</a> para notificarnos su nueva direcci\u00F3n postal.",
"hist_case_status" : null
},
"message" : "Query was successful for payload {'receipt_number': 'EAC9999103402'}"
}

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

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.