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
- App Name: This can be anything
- Callback URL: This is optional unless using three-legged OAuth.
- Description: Tell us about your App and their main functions
- 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:
- Currently Unavailable
Using CURL to get your Access Token
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' \
"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" : "firstname.lastname@example.org",
"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
"expires_in": "1799", //--in seconds
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@example.com 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.