NCI uses Okta for authentication and authorization services for the CTRP applications and APIs. This page describes the tasks required to obtain the proper authorization to use the 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 Okta CTRP user account to access CTRP applications (CTRP Registration and CTRP Accrual) and use the CTRP API. For instructions on requesting an Okta CTRP account, refer to the following: Creating New NCI CTRP User Accounts.

2. Obtain Okta Client ID and Client Secret

Once your Okta CTRP user account has been created, contact CTRP_support@nih.gov to request authorization to use the CTRP APIs. CTRP Support will review the request and, if approved, will generate a Client ID and Client Secret associated with your account and provide these key values to you. The Client ID and Client secret are required parameters to generate an Okta access token. 

3. Generate Okta access token

All service endpoints require Okta access 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.

Method: POST

Service Endpoints:

Int

https://bioappdev.okta.com/oauth2/aus3ym6wniM6O3MGE297/v1/token

Stage

https://bioappdev.okta.com/oauth2/aus478s3eb0x3du23297/v1/token

Production

Headers

Content-Type

application/x-www-form-urlencoded

Accept


application/json

Parameters:

grant_type

client_credentials

Authorization:

Authorization TypeBasic

Username

Client ID generated by CTRP Support for the user account

Password

Client Secret generated by CTRP Support for the user account

Response:

{"token_type":"Bearer","expires_in":1800,"access_token":<accessToken>}

The access token will expire 1 hour after being generated (1800 seconds).

4. Call REST Service with Bearer Authentication

Once the access token has been generated, it will need to be included in the 'Authorization: Bearer' parameter when submitting API requests. The following example uses the accrual-services URL in the Stage environment and lists the required header and parameters values.

Method: GET

Service Endpoint:

Stage

https://trials-int.nci.nih.gov/accrual-services/trials/{idType}/{trialId}/sites/po/{id}

idTypeType of identifier you want to use to identify a study in CTRP. Possible values: pa, nci, ctep, dcp
trialIDTrial identifier value itself
idPO identifier of the organization that is the site on the study

Headers

Content-Type

application/xml

Accept

text/plain

Parameters:



Authorization:

Authorization TypeBearer Token

Token

Access Token generated in step 3 above

Body:

<tns:studySubjects xmlns:tns="gov.nih.nci.accrual.webservices.types"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="gov.nih.nci.accrual.webservices.types ../../src/resources/ws.xsd ">
    <tns:studySubject>
        <tns:identifier>SU001</tns:identifier>
        <tns:birthDate>2002-01-01</tns:birthDate>
        <tns:gender>Female</tns:gender>
        <tns:race>Black or African American</tns:race>
        <tns:ethnicity>Not Hispanic or Latino</tns:ethnicity>
        <tns:country>USA</tns:country>
        <tns:zipCode>22201</tns:zipCode>
        <tns:registrationDate>2014-01-01</tns:registrationDate>
        <tns:methodOfPayment>MEDICAID_AND_MEDICARE</tns:methodOfPayment>
        <tns:disease codeSystem="ICD9">861.20</tns:disease>       
    </tns:studySubject>
</tns:studySubjects>

Response:

JSON or XML data, depending on which service is being used.

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."

}

Invalid/Expired access token<Please provide><Please provide>

Password Rotation

The Client ID and Client Secret need to be updated on a yearly basis. Contact the CTRP Support to obtain a new Client ID / Client Secret combination.

CTRP REST services

See the following for additional details on the various CTRP web services: