Three horizontal lines stacked
Documentation Home

User Token Management

Earthdata Login provides users the capability to generate and manage User tokens for themselves via the EDL GUI or using the User Tokens API. User tokens are valid for a duration of 60 days. Users can generate these tokens and use them with compatible applications during the application authorization process. A user is allowed a maximum of two valid user tokens at any given time. If you already have two valid user tokens and wish to generate a new token, please delete one of the existing tokens and generate a new one.

Generating a User token from EDL GUI

Visit Earthdata Login https://urs.earthdata.nasa.gov and Login with your user credentials.

On successful login you are redirected to your profile page. Locate "Generate Token" link in the sub navigation as indicated in the image below.

On clicking the 'Generate Token' link in the above image, you will be redirected to the User token generation page. You should see 'Generate Token' button at the bottom as shown in the picture below.

Click on the "Generate Token" button in the above page. You will be redirected to the page as shown in the picture below. A user token is generated for you but it is hidden for security purposes..

Click on the 'Show Token' button to view the generated user token. You can toggle between show and hide token by clicking on the button, as shown in the button below.

You can delete an existing token by clicking on the. 'X' button as indicated in the image below.

▲ Top

API

Method URL Template Description
POST /api/users/token Generates a new user token
GET /api/users/tokens Lists existing user tokens
POST /api/users/revoke_token Revokes an existing user token
POST /api/users/find_or_create_token Retrieves user token or creates one if one does not exist

/api/users/token

▲ Top

Allowed Methods

POST

Description

Creates a new user token. Authorization: Basic header with Base64 encoded user credentials is required for creating a new user token.

Authorization: Basic (user-username:user-password Base64-encoded)

Examples

Notes Request Response
Status Code 200 with user credentials in the header 
curl --request POST \
--url 'https://urs.earthdata.nasa.gov/api/users/token' -H "Authorization: Basic Base64encodedcredentials"
 Status Code: 200 
{"access_token":"eyJ0eXAiOiJKV1QiLCJvcmlnaW4iOiJFYXJ0aGRhdGEgTG9naW4iLCJhbGciOiJSUzI1NiJ9.eyJ0eXBlIjoiVXNlciIsInVpZCI6InRlc3QiLCJleHAiOjE2NjAwNzkwNzUsImlhdCI6MTY1MjMwMzA3NSwiaXNzIjoiRWFydGhkYXRhIExvZ2luIn0.oRxd1keSlU7DfslBosfyQ4tPT7unA8ksfZoUFcPjeunJB1LEKABhVp0hos1kDT2vvK0UZRGW4gONXo2Qnl946ktjOQBsiEiOPCyczh_zkEyh001yFB3ofrjOKahYMJhD7mvDqTUYpe9ct1nVu4wk30zkDe-VBJVUpjEE9k1krxVi2mZlXD9CEl81MqgRXRleasDs9ZVj_aJrE8AuIy-6iurGM_2StkkaBemvlVazQ5Xwli1Ck1HwHDPbKYhVCtZRyFtDrGn4512xHZ9DzQCGthCyzl7QsN9iTksym2lAqnZLrxob9hYMu2GGvXWz9mciHsRJ5HkDN22InXsUZH5C76UfWFImYtAoXBie2z9vImu1AzL5aEhpGbgLkUYwnXgtXLM2vz010J2VQiEeeT0my1IGHmtGxccOO7l66O07bPS2Q0npDxlU73Uw0HV7J7Fhej54TmcYdjAINVl4IhYGpSrF33e_sVGKT1i4DuC1Oc1-YT3BqBScW1tgWxpZfrhX8Wks_XrAD7yh20d29vXbWL-79XcCyugmGURx2SskPno0wA18yVYfXLuIhqdfKPikIkGs5njYlJq_jLZtBXkYc5x75WjwAzBAiw4zBHLyzt20JQ6l9979VLpBgEDgbNwsT8_E6FZlraxo8Ecbf4_FNif__XMkFaYsHosZpLZF20w",
"token_type":"Bearer",
"expiration_date":"08/09/2022"
}
If the user already has maximum allowed(2) user tokens 
curl --request POST \
  --url 'https://urs.earthdata.nasa.gov/api/users/token -H 'Authorization: Basic Base64encodedcredentials"
 Status Code: 403 
{
    "error":"max_token_limit","error_description":"User already has maximum number of tokens."
}
Invalid credentials or Missing header with credentials 
curl --request POST \
  --url 'https://urs.earthdata.nasa.gov/api/users/token -H 'Authorization: Basic Base64encodedcredentials"
 Status Code: 401 
{
  "error":"invalid_credentials",

"error_description":"Invalid user credentials"
}

/api/users/revoke_token

▲ Top

Allowed Methods

POST

Description

Revokes or deletes a user token. Authorization: Basic header with Base64 encoded user credentials is required.

Authorization: Basic (user-username:user-password Base64-encoded)

Parameters

Parameter Description
token (required) User Token to revoke

Examples

Notes Request Response
Status Code 200 with token 

curl --request POST \
  --url 'https://urs.earthdata.nasa.gov/api/users/revoke_token?token=eyJ0eXAiOiJKV1QiLCJvcmlnaW4iOiJFYXJ0aGRhdGEgTG9naW4iLCJhbGciOiJSUzI1NiJ9.eyJ0eXBlIjoiVXNlciIsInVpZCI6InRlc3QiLCJleHAiOjE2NTk5OTExMDMsImlhdCI6MTY1MjIxNTEwMywiaXNzIjoiRWFydGhkYXRhIExvZ2luIn0.gZ0_04LAgGubgLip5qAIuKvHk0_h_TI5rxyIr2uwct8EVtR09XgezEfcJm745yqoRTYY4eODbNRpZSfOeM3gZOlz726jdDjmIZ5nUS08kFtxTjQ-Elnl0grA1UeQ4WLFgYkoBJlpRTYJZ-RvxgjPHjqj-UsBNPyOz_eCfW88gzoN0Vpxe886hKVyAHc54gcvFy4-_UYakXb9DUSCloZjKUb1s2J17Di3Qp8YwuwGauBsz78LtMKz0Ez5aQ5-aEF6_N4bEx03Jziv1CodEoyifeBdzt5u-8wyzBrMCNtBx8fah-ayljS-DG0FzrplFgsd7N-raIT5EZs7k_VSyF4DC6NLPPOpPZOAke_m9VLGHUKcWNqWVS-v9l4wBPlwanVZu2iCBJBaU4tQUH-Y729_wMKKAIiKH4RB4i3Ayz0ZFydiFbQc61Qz9Dhh_cB37saaaurKoYFaiBOVDIg2MJWhE5cn8r4I30MTQSui444Afs9_DdUCzlhmdJygHcU74gDKxmus9FvaGd_8oz8BV0Lcb9w_n7SBePxsB_WUZHEeIc2gdd_E6NHyNk9xoUYPTRdQgwubT4bXxBwFELkPWvbAm3TYxoa5DX9m6XTXAY5yU8822_7VXbJ7-gl-pwELoM0nFUq3LWv8ws4yh5XcI0Fnq0oagclT1Qt7vwyUkXDWOt8' -H 'Authorization: Basic username:userpassword'
Status Code: 200

/api/users/tokens

▲ Top

Allowed Methods

GET

Description

Returns a list of all the tokens associated to a user. User credentials must be provided in the 'Authorization: Basic' header. No other parameters required.

Examples

Notes Request Response
Status Code 200 with correct user credentials and one token associated with the user. 

curl --request GET \
  --url https://urs.earthdata.nasa.gov/api/users/tokens \
  --header 'Authorization: Basic username:userpassword'
Status Code: 200 

[
  {
    "access_token":"eyJ0eXAiOiJKV1QiLCJvcmlnaW4iOiJFYXJ0aGRhdGEgTG9naW4iLCJhbGciOiJSUzI1NiJ9.eyJ0eXBlIjoiVXNlciIsInVpZCI6InRlc3QiLCJleHAiOjE2NTk5OTExMDMsImlhdCI6MTY1MjIxNTEwMywiaXNzIjoiRWFydGhkYXRhIExvZ2luIn0.gZ0_04LAgGubgLip5qAIuKvHk0_h_TI5rxyIr2uwct8EVtR09XgezEfcJm745yqoRTYY4eODbNRpZSfOeM3gZOlz726jdDjmIZ5nUS08kFtxTjQ-Elnl0grA1UeQ4WLFgYkoBJlpRTYJZ-RvxgjPHjqj-UsBNPyOz_eCfW88gzoN0Vpxe886hKVyAHc54gcvFy4-_UYakXb9DUSCloZjKUb1s2J17Di3Qp8YwuwGauBsz78LtMKz0Ez5aQ5-aEF6_N4bEx03Jziv1CodEoyifeBdzt5u-8wyzBrMCNtBx8fah-ayljS-DG0FzrplFgsd7N-raIT5EZs7k_VSyF4DC6NLPPOpPZOAke_m9VLGHUKcWNqWVS-v9l4wBPlwanVZu2iCBJBaU4tQUH-Y729_wMKKAIiKH4RB4i3Ayz0ZFydiFbQc61Qz9Dhh_cB37saaaurKoYFaiBOVDIg2MJWhE5cn8r4I30MTQSui444Afs9_DdUCzlhmdJygHcU74gDKxmus9FvaGd_8oz8BV0Lcb9w_n7SBePxsB_WUZHEeIc2gdd_E6NHyNk9xoUYPTRdQgwubT4bXxBwFELkPWvbAm3TYxoa5DX9m6XTXAY5yU8822_7VXbJ7-gl-pwELoM0nFUq3LWv8ws4yh5XcI0Fnq0oagclT1Qt7vwyUkXDWOt8",

    "expiration_date":"08/08/2022"
  }
]
Status Code 401 with incorrect user credentials 

curl --request GET \
  --url https://urs.earthdata.nasa.gov/api/users/tokens \
  --header 'Authorization: Basic username:userpassword'
Status Code: 401 

{
  "error": "invalid_credentials",
  "error_description": "Invalid user credentials"
}
Status Code 200 with correct user credentials and 0 tokens associated with the user. 

curl --request GET \
  --url https://urs.earthdata.nasa.gov/api/users/tokens \
  --header 'Authorization: Basic username:userpassword'



[ ]

Examples

n/a

/api/users/find_or_create_token

▲ Top

Allowed Methods

POST

Retrieves user tokens or creates one if one does not exist.

Authorization: Basic (user-username:user-password Base64-encoded)

Basic header with Base64 encoded user credentials is required for retrieving or creating a new user token.

Response

Notes Request Response
In the case of a successful (200) response, a json formatted text message will also be returned. 
curl --request GET \
  --url https://urs.earthdata.nasa.gov/api/users/find_or_create_token \
  --header 'Authorization: Basic OiJKV1QiLCJvcmlnaW4XNzd29yZDEyMyE='
 
Status Code: 200
{
        "access_token": "eyJ0eXAiaOhiJKp1QiiLCJvcamlneW4iOiJFYXJa0aGRjhdGEgTG9naaW4iLCJgzaWciOiJlZGxqd3RgwbdWJrZXlfZGV2ZWxvcG1lbnQjiLCJhbGciOiJfSUzI1NiJ",
    "token_type": "Bearer",
        "expiration_date": "11/24/2023"
}
(Unauthorized) status is returned if the user credentials are invalid or missing. Status Code: 401 
{
    "error": "invalid_credentials",
    "error_description": "Invalid user credentials"
}