...
- The application requests credentials. The credentials you pass are different depending on if you want to access public or restricted data (see above).
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
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.
...
Requesting a Token
...
to Use with Public Data
If you don't have a TCIA account and want to test an API on this page, you can access public data using the NBIA guest account with no password, as followsA successful token request returns a standard access token in JSON format.
Code Block |
---|
title | Sample Token Return Value |
---|
|
{"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
Call for Testing an NBIA REST API without a Token |
|
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
A successful token request returns a standard access token in JSON formatMake a note of the access token you received and pass it with the REST service call.
Code Block |
---|
title | Sample NBIA Search with Authentication REST 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.
Refreshing the Token
|
{"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 callThe time it takes tokens to expire is configurable but is currently two hours.
Code Block |
---|
title | Sample Request for Refreshing the TokenNBIA Search with Authentication REST API Call |
---|
|
# Request for refreshing the token
$ modality values
curl -X -v -d "refresh_token=7c2414a1-1f2f-4c9e-82a0-69fcb9fd18ed&client_id=nbiaRestAPIClient&client_secret=ItsBetweenUAndMe&grant_type=refresh_token" -X POSTH "Authorization:Bearer c428d42c-9eed-4f5d-8007-416d46be9b52" -k "https://services.cancerimagingarchive.net/nbia-api/oauth/token
/nbia-api/oauth/token"services/v2/getModalityValuesAndCounts?Collection=LIDC-IDRI" |
A successful service request returns the value in a defined format.
Refreshing the Token
The time it takes tokens to expire is configurable but is currently two hoursIn the following result, 119
is the seconds before the token expires.
Code Block |
---|
|
{"access_token":"bbe4aa2c-7235-41ad-9770-31619d3dbd15","token_type":"bearer","refresh_token":"671bb72b-f929-4ef5-a4d7-b52341a6007a","expires_in":119} |
Logging Out
Request for Refreshing the Token |
|
# Request for refreshing the token
$ curl -X -v -d "refresh_token=7c2414a1-1f2f-4c9e-82a0-69fcb9fd18ed&client_id=nbiaRestAPIClient&client_secret=ItsBetweenUAndMe&grant_type=refresh_token" -X POST -k https://services.cancerimagingarchive.net/nbia-api/oauth/token
/nbia-api/oauth/token" |
In the following result, 119
is the seconds before the token expiresThe following is an example request to log out.
Code Block |
---|
title | Sample Request to Log Out |
---|
|
# Request for logout
$ curl -H "Authorization:Bearer caa278aa-e7a9-45b8-a7ec-2c83d4b03cc0" -k "https://services.cancerimagingarchive.net/nbia-api/logout" |
If successful, the request returns the following text.
Code Block |
---|
|
You Have Logged Out successfully. |
...
|
{"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 request to log out.
Code Block |
---|
title | Sample Request to Log Out |
---|
|
# Request for logout
$ curl -H "Authorization:Bearer caa278aa-e7a9-45b8-a7ec-2c83d4b03cc0" -k " |
...
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.
Code Block |
---|
title | Call for Testing an NBIA REST API without a Token |
---|
|
curl -d "username=nbia_guest&password=&client_id=NBIA&grant_type=password" -X POST -k https://services.cancerimagingarchive.net/nbia-api/oauth/tokenlogout" |
If successful, the request returns the following text.
Code Block |
---|
|
You Have Logged Out successfully. |
Excerpt Include |
---|
| NBIA Search REST API Guide |
---|
| NBIA Search REST API Guide |
---|
nopanel | true |
---|
|
Return Values
This section lists and explains the return values of the APIs included in both tables above.
...