U.S. flag

An official website of the United States government

Dot gov

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Https

Secure .gov websites use HTTPS
A lock () or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

New Developer Team App and Key Rotation Policies: For more information, see article Developer Teams and Developer Team Apps and API Key Management Policy

  1. Home

How to Get Access Tokens with Client Credentials

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 Team App on the platform. Your Developer Team App will be assigned Client Credentials: a Client ID and a Client Secret.

  • Client ID: is a public key
  • Client Secret: must never be made public

Always secure your Client Id and Client Secret following cybersecurity best practices. For more information, continue reading Best Practices for Storing your Client Credentials below.  

 

Your Client Credentials are 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.

OAuth 2.0 Authentication Workflow Diagram

OAuth 2.0 Authentication Workflow Diagram
  1. Make a request to authenticate your app.
  2. A response is returned providing an Access Token
  3. Place the Access Token in the header to make a request to authenticate request to the Resource Server API
  4. A response is returned from the Resource Server API with the requested data
     

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.

The following are best practices we look for when you demo your application for production access. We will require use of a back end mediator that routes request through a secure backend service that your company/organization controls. 

Secrets Management Service

If your application is running in a cloud-based or complex environment, we recommend use of a Secrets Management Service as they are designed to centralize and protect your credentials throughout their entire lifecycle. 

Backend services access the secrets manager during runtime, avoiding the need to hardcode these variables in your source code, configuration files or build logs. 

Environment Variables

For smaller applications, environment variables are commonly used to securely store credentials by keeping them out of your code base. Variable set on your system or server are accessible during runtime via the .env file. 

NOTE: you must include .env files in .gitignore to prevent committing this file to your repositories.

Avoid Client Side Storage

Never  store  your Client Credentials in a front-end application that is delivered to your end user (e.g. web applications or mobile apps).

 

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'}"
}

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:

  • Available when you Pass your Demo

Client Credentials are issued through the Developer Team App creation. You can complete this in a few simple steps.

  1. Login/Signup at https://developer.uscis.gov/
  2. Click on Teams
  3. Click on Team Apps in the Upper Right Menu
  4. Click on Add App
  5. 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)
  6. Add App

Completion of your Developer Team 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