 |
Page History
This page describes the tasks required to obtain the proper authorization to use the NCI CTRP API. For any questions or support contact CTRP_support@nih.gov.
1. Create NCI CTRP user account
All users are required to have a valid CTRP user account to use NCI CTRP REST servicesaccess CTRP applications (CTRP Registration and CTRP Accrual) and use the CTRP API. For instructions on requesting a CTRP account, refer to the following: Creating New NCI CTRP User Accounts. All service endpoints require Okta token authentication with your .
2. Obtain NCI CTRP Client ID and Client Secret
Once your NCI CTRP user account has been created, contact . Contact CTRP_support@nih.gov to have an NCI CTRP request access to use the CTRP APIs. CTRP Support will review the request and, if approved, will generate a Client ID and Client secret generated Secret for your CTRP REST account. Once you have received your account and provide these key values to you. The Client ID and Client Secret from CTRP Support, follow the steps below to use the NCI CTRP and PRS REST services. An Okta authentication token is required to use these services. There are different processes between PRS and CTRP users, see below for explanations.
For CTRP REST services
Users accessing the CTRP Accrual, Trial Registration, Participating Site REST services. See the following for additional details on the various CTRP web services:
- NCI CTRP Trial Registration REST Service Guide
- NCI CTRP Accrual REST Service Guide
- NCI CTRP Participating Site REST Service Guide
1. Get Okta access token
The following endpoint will generate an Okta access token provided the parameters passed in are valid. Please contact CTRP_support@nih.gov for any questions or issues in regards to generating the Okta access token.
secret are required parameters to generate an Okta Authentication Token.
3. Generate Okta access token
All service endpoints require Okta token authentication. To generate an Okta access token, a request must be made to the environment service endpoint using a valid Client ID and Client Secret. See below for additional details on how to construct the access token request.
Service Endpoints:
Int: <Provide Int URL here>
Stage: @bioappdev.okta.com/oauth2/aus3ym6wniM6O3MGE297/v1/token” \
Production: <Provide Prod URL here>
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=client_credentials" \
Parameters:
clientId | Client ID generated by CTRP Support for the user account |
clientSecret | Client Secret generated by CTRP Support for the user account |
Response:
{"token_type":"Bearer","expires_in":43200,"access_token":<accessToken>}
...
| Info |
|---|
The access token will expire 12 hours after being generated (43,200 seconds). |
4. Call REST Service with Bearer Authentication
Once the Include the access token in the 'Authorization: Bearer' parameter when submitting API requests. The following example uses the accrual-services URL and lists the required header and parameters.
...
--header 'Authorization: Bearer <accessToken>'
Parameters:
accessToken | Access Token generated in step 13. |
| idType | nci |
| trialID | NCI-2019-00038 |
| id | 7434 |
Response:
JSON or XML data, depending on which service is being used.
For PRS REST Services
1. Get Okta access token
The following endpoint will generate an Okta access token provided the parameters passed in are valid. Please contact CTRP_support@nih.gov for any questions or issues in regards to generating the Okta access token.
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. Call REST Service with Bearer Authentication
Include the access token in the 'Authorization: Bearer' parameter when submitting API requests.
...
--header 'Authorization: Bearer <accessToken>'
Parameters:
accessToken | Access Token generated in step 1. |
NCT | Trial ID (e.g. NCI-2017-02883) |
Response:
XML data
Error Codes for the 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." } |
For CTRP REST services
Users accessing the CTRP Accrual, Trial Registration, Participating Site REST services. See the following for additional details on the various CTRP web services:
