Once you have received your Client ID and Client Secret from CTRP Support, follow the steps below to use the NCI CTRP REST services
Download XML from CTRP API
1. Get OKTA access token
The following endpoint will generate an Okta access token provided the parameters passed in are valid.
POST:
curl --request POST “https://<clientId>:<clientSecret>@bioappdev.okta.com/oauth2/aus3ym6wniM6O3MGE297/v1/token” \
--header “Accept: application/json” \
--header “Content-Type: application/x-www-form-urlencoded” \
--data-urlencode “grant_type=password” \
--data-urlencode “username=<username>” \
--data-urlencode “password=<password>” \
--data-urlencode “scope=openid”
Parameters:
clientId | Client ID |
clientSecret | Client Secret |
username | CTRP OKTA account email ID |
password | CTRP OKTA account password |
Response:
{"token_type":"Bearer","expires_in":43200,"access_token":<accessToken>,"scope":"openid","id_token":<idToken>}
2. Get XML
Include the access token in the 'Authorization: Bearer' parameter when submitting API requests.
GET:
curl --location --request GET 'https://trials.nci.nih.gov/services/trials/<NCT> ' \
--header 'Content-Type: application/json' \
--header 'Accept: application/xml' \
--header 'Authorization: Bearer <accessToken>'
Parameters:
accessToken | Access Token |
NCT | Trial ID (e.g. NCI-2017-02883) |
Response:
XML data
Password Rotation
The Client ID and Client Secret will be updated every year. CTRP team will provide new Client ID / Client Secret combination to PRS two weeks before each update. During the two-week grace period, both old and new credentials will work.
Test Site
https://trials-stage.nci.nih.gov/services/trials/
Error Codes
Table 1. Error Code for OKTA API
Error | Code | Message |
Invalid Client Id | 401 | { "errorCode": "invalid_client", "errorSummary": "Invalid value for 'client_id' parameter.", "errorLink": "invalid_client", "errorId": "oaejDJuWCiRTQeH8n6WG2116A", "errorCauses": [] } |
Invalid Client Secret | 401 | { "error": "invalid_client", "error_description": "The client secret supplied for a confidential client is invalid." } |
Invalid User Credentials / Account Locked* | 400 | { "error": "invalid_grant", "error_description": "The credentials provided were invalid." } |
*User OKTA account will be locked after multiple inputs of wrong credentials. The account will be unlocked automatically after 15 minutes.
Table 2. Error Code for CTRP API
Error | Code | Message |
Invalid Token | 401 | HTML1 |
Invalid Request | 400 | <error>Abbreviated trials are not eligible for XML Export.</error> |
Invalid Request | 400 | <error>This trial is in review in CTRP by the CTRO is not eligible to be uploaded to PRS at this time.</error> |
Forbidden | 403 | <error>Authorization failed. User does not have ownership of the trial.</error> |
Not Found | 404 | <error>No match found based on the NCI ID that was provided.</error> |
Internal Server Error | 500 | <error>An error occurred while retrieving the information from CTRP. Please contact the CTRP Help Desk at ctrp_support@nih.gov.</error> |
Other Run Time Error | 500 | HTML2 |
Appendix
1. Error message for invalid token
<html>
<head>
<title>JBoss Web/7.5.7.Final-redhat-1 - JBWEB000064: Error report</title>
<style>
<!--H1 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:22px;} H2 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:16px;} H3 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:14px;} BODY {font-family:Tahoma,Arial,sans-serif;color:black;background-color:white;} B {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;} P {font-family:Tahoma,Arial,sans-serif;background:white;color:black;font-size:12px;}A {color : black;}A.name {color : black;}HR {color : #525D76;}
-->
</style>
</head>
<body>
<h1>JBWEB000065: HTTP Status 401 - </h1>
<HR size="1" noshade="noshade">
<p><b>JBWEB000309: type</b> JBWEB000067: Status report</p>
<p><b>JBWEB000068: message</b> <u></u></p>
<p><b>JBWEB000069: description</b> <u>JBWEB000121: This request requires HTTP authentication.</u></p>
<HR size="1" noshade="noshade">
<h3>JBoss Web/7.5.7.Final-redhat-1</h3>
</body>
</html>
2. Error message for run time error
<html>
<head>
<title>JBoss Web/7.5.7.Final-redhat-1 - JBWEB000064: Error report</title>
<style>
<!--H1 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:22px;} H2 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:16px;} H3 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:14px;} BODY {font-family:Tahoma,Arial,sans-serif;color:black;background-color:white;} B {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;} P {font-family:Tahoma,Arial,sans-serif;background:white;color:black;font-size:12px;}A {color : black;}A.name {color : black;}HR {color : #525D76;}
-->
</style>
</head>
<body>
<h1>JBWEB000065: HTTP Status 500 - </h1>
<HR size="1" noshade="noshade">
<p><b>JBWEB000309: type</b> JBWEB000067: Status report</p>
<p><b>JBWEB000068: message</b> <u></u></p>
<p><b>JBWEB000069: description</b> <u>JBWEB000145: The server encountered an internal error that prevented it from
fulfilling this request.</u></p>
<HR size="1" noshade="noshade">
<h3>JBoss Web/7.5.7.Final-redhat-1</h3>
</body>
</html>
