Security Overview

NCCPA's APIs are secured with OAuth 2.0. In order to access any of our APIs, you must be approved by NCCPA and registered as an API client. A registered client must obtain an access token from NCCPA's authorization server prior to accessing any API resources. Once you're approved for API access by NCCPA, you should receive an email with an invitation to login to the developer portal. There, you can retrieve your client ID and private client secret which are assigned by NCCPA and required for API access.

To use the Board Certification Status API, you must authorize with NCCPA's authorization server using the OAUTH client credentials grant type. The CME API allows approved third parties to log CME on behalf of a PA and thus requires the PA's permission. To request the PA's permission and obtain a token for access to a PA's resources, clients must implement the OAUTH authorization code flow.

All API calls and authorization requests must be transmitted over https. Approved clients should protect their client secret by encrypting and storing in a secure datastore. Your client secret should never be transmitted over an insecure connection. It should never be embedded in a web page or present in an http query string where it could be compromised.

Client Credentials

To obtain an access token using the client credentials grant type, make a POST request to NCCPA's token endpoint using your client ID (client_id) and private client secret (client_secret). The request should also contain a grant_type of "client_credentials". The client ID and client secret can be obtained by logging in to the developer portal. The endpoint used to authenticate and retrieve an access token is:

https://api.nccpa.net/oauth/token

The token endpoint supports both HTTP basic authentication and POST requests. The former embeds the "client_id" and "client_secret" in an Authorization header using base64 encoding and the latter sends the "client_id" and "client_secret" in the request body.

If authentication is successful, a JSON data structure containing an access token (along with other metadata) is returned in the response body. A sample response after successful authentication looks like:

{
    "access_token":"8RqQPslfowij0s0903jlSKS93KW202",
    "token_type":"bearer",
    "expires_in":3599,
    ".issued": "Wed, 21 Dec 2016 19:15:25 GMT",
    ".expires": "Wed, 21 Dec 2016 20:15:25 GMT"
}

Once the access token is issued, the client may access API resources using the token in the HTTP request header as a bearer token. A sample request using a bearer token:

GET /someapiresource
Host: api.nccpa.net
Authorization: Bearer 8RqQPslfowij0s0903jlSKS93KW202

Access tokens obtained through the client credential grant flow are valid for 1 hour after which a new access token must be requested for continued access to API resources. NCCPA recommends that you do not store this access token, but instead request a new access token each time you need to access the API.

Authorization Code

Clients approved for access to the CME API should use the authorization code flow to obtain permission from PAs to log CME on their behalf. This flow allows the PA to authenticate to NCCPA's web services and grant permissions to a 3rd party without requiring the PAs credentials to flow through the 3rd party. Clients should never ask a PA to enter their NCCPA user id and password.

For an overview of the authorization code flow, see this graphic. Note that, in OAUTH terms, the PA is the "resource owner", NCCPA hosts the "authorization server", the "user agent" is the PA's browser, and the "client" is your web application.

To initiate the authorization code flow, client's will redirect a user's browser to NCCPA's authorization endpoint along with their client ID (client_id), redirect URI (redirect_uri), unique state string (to prevent CSRF attacks or identify your user), and with a response_type of "code". NCCPA's authorization endpoint is:

https://api.nccpa.net/oauth/authorize

An example redirect URL would look like:

https://api.nccpa.net/oauth/authorize?response_type=code&client_id=[YOUR_CLIENT_ID]&redirect_uri=[YOUR_REDIRECT_URI]&scope=Log_CME&state=[YOUR_STATE_STRING]

NCCPA will prompt the user to authenticate and to allow or deny your application to log CME on their behalf. The only supported scope (permission) at this time is "Log_CME", and you must pass that in your query string. If the user authenticates and grants permissions, an authorization code will be returned by redirecting the user to your redirect URI. Note that your redirect URI must be pre-configured and must be accessible with TLS (https). It can be set in the developer portal. A URL with an authorization code will look like:

https://[YOUR_REDIRECT_URI]?code=[AUTHORIZATION_CODE]&state=[YOUR_STATE_STRING]

You should validate that the value of "state" matches the value you passed to the redirect URL. The authorization code cannot be used to access the API. Once you have an authorization code, you must exchange that for an access token at NCCPA's token endpoint by making a POST request with your client ID (client_id), client secret (client_secret), authorization code (code), and redirect_uri. Also, specify a grant_type of "authorization_code" in your token request. An authorization code can only be used once to request an access token. Use the following endpoint to request an access token with your authorization code:

https://api.nccpa.net/oauth/token

Given a valid client ID, client secret, redirect URI, and authorization code, NCCPA will return a JSON object with an access token, a refresh token, and related metadata. Here's an example response:

{
    "access_token":"8RqQPslfowij0s0903jlSKS93KW202",
    "token_type":"bearer",
    "expires_in":3599,
    "refresh_token": "FsrhbHgecuBR4htQTHF0iajwlvNa",
    ".issued": "Wed, 21 Dec 2016 19:15:25 GMT",
    ".expires": "Wed, 21 Dec 2016 20:15:25 GMT"
}

Once the access token is issued, the client may access API resources using the token in the HTTP request header as a bearer token. A sample request using a bearer token:

POST /someapiresource HTTP/1.1
Host: api.nccpa.net
Authorization: Bearer 8RqQPslfowij0s0903jlSKS93KW202

Refresh Tokens

The access token, which is required to access the API, is only valid for a period of 1 hour. Your application should not store the access token. Instead, your application should store the refresh token that's returned with the access token and associate it with the user that granted permissions to your application. This refresh token uniquely identifies the PA and the permissions they've granted to your application, but it cannot be used to access the API. Instead, you must exchange the refresh token for a new access token.

To obtain an access token using a refresh token, make a POST request to NCCPA's token endpoint using your client ID (client_id), client secret (client_secret), and refresh token (refresh_token). The request should also contain a grant_type of "refresh_token". The endpoint used to authenticate and retrieve an access token with a refresh token is:

https://api.nccpa.net/oauth/token

Refresh tokens are valid for 180 days from the time that they are issued. A new refresh token is issued each time an access token is issued. This effectively provides a "sliding" expiration for you application to access the CME API on behalf of a PA. As long as you are requesting new access tokens (using non-expired refresh tokens) and storing new refresh tokens, your application can call the API on behalf of that PA without ever needing to request that the PA re-authorize your application. However, if you allow your refresh token to expire, you'll no longer be able to acquire an access token and will have to prompt the PA to re-authorize your application.

Also, note that a PA or NCCPA can revoke permissions to your application at any time. If this happens, you will not be able to obtain a new access token nor will any previously issued access tokens grant permissions to the API on that PA's behalf, even if the access token is not expired. Your application should handle expired access tokens and refresh tokens as well as non-expired tokens which no longer grant access to the API on behalf of a PA.

Note that if the access token expires or is revoked, API endpoints will return a 401 Not Authorized response. If http requests to either the authorize endpoint or the token endpoint are malformed or are not valid for other reasons, then a 400 Bad Request response will be returned.