...

1. The application requests credentials. The credentials you pass are different depending on if you want to access public or restricted data (see above).

2. The application sends a request to the service using the credentials you provided as a query string for the body. 

   • grant_type=password
   • username
   • password

3. The service responds with access token details and expiration information.

   • access_token
   • expires_in
   • token_type

   The application makes a request for resources using the returned access token. All APIs listed for accessing public data also support secure access to restricted data with an additional parameter for the access token. 

Testing an API with Public Data

...

How a Token is Returned/Granted/Given

A successful token request returns a standard access token in JSON format.

curl -d "username=nbia_guest&password=&client_id=NBIA&grant_type=password" -X POST -k https://services.cancerimagingarchive.net/nbia-api/oauth/token

How a Token is Returned/Granted/Given

{"access_token":"f7889076-b3e4-4768-9419-3cd973adda76","token_type":"bearer","refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":7199}

Using the Token in an API Call

Make a note of the access token you received and pass it with the REST service callA successful token request returns a standard access token in JSON format.

{"access_token":"f7889076-b3e4-4768-9419-3cd973adda76","token_type":"bearer","refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":7199}

Using the Token in an API Call

...

# Request for modality values
curl -H "Authorization:Bearer c428d42c-9eed-4f5d-8007-416d46be9b52" -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValuesAndCounts?Collection=LIDC-IDRI"

A successful service request returns the value in a defined format. 

Testing an API with Public Data

If you don't have a TCIA account and want to test an API, you can access public data using the NBIA guest account with no password, as follows.

# Request for modality values
curl -H "Authorization:Bearer c428d42c-9eed-4f5d-8007-416d46be9b52"d "username=nbia_guest&password=&client_id=NBIA&grant_type=password" -X POST -k "https://services.cancerimagingarchive.net/nbia-api/services/v2/getModalityValuesAndCounts?Collection=LIDC-IDRI"

A successful service request returns the value in a defined format. 

...

oauth/token

Refreshing the Token

The time it takes tokens to expire is configurable but is currently two hours.

...

{"access_token":"bbe4aa2c-7235-41ad-9770-31619d3dbd15","token_type":"bearer","refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":119}

...

Logging Out

The following is an example requet to log out.

# Request for logout   
      
$ curl -H "Authorization:Bearer caa278aa-e7a9-45b8-a7ec-2c83d4b03cc0" -k "https://services.cancerimagingarchive.net/nbia-api/logout"

ResultIf successful, this request returns the following text.

 You Have Logged Out successfully.

...