How to Get Access Tokens with Client Credentials

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 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.

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

Request and Access Token using Client Credentials Grant Type

Curl 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": "[email protected]",
 "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'}"
}

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

{
 "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": "[email protected]",
 "token_type": "Bearer",
 "issued_at": "1720723543834",
 "client_id": "######",
 "access_token": "######",
 "application_name": "######-###-###-###-######",
 "scope": "",
 "expires_in": "1799",
 "refresh_count": "0",
 "status": "approved"
}

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 [email protected] for any questions.