API Access

Programming isn’t about what you know; it’s about what you can figure out.

– Chris Pine, Learn to Program

To make an API call to the PCMI APIs, you must be authorized, and make a well formed request based on the API specifications of the API you are intending to call.

What is Authorization?

Authorization is, according to the OWASP Authorization Cheat Sheet, defined as:

...the process of verifying that a requested action or service is approved for a specific entity

How do I get Authorized?

To call most modern PCMI APIs, you will need a JWT token and an API key.
To get a JWT Token, you'll need a Client Id and Secret

Get a Client Id and Secret

Client Ids and Secrets are available upon request only.

Make the call to get a JWT Token

JWT tokens can be acquired by calling our Authorization Provider

Using Basic Authorization, one can make a POST to

https://{{auth-host}}/oauth2/token

Where {{auth-host}} is the Production or UAT auth host as defined below:

Hosts

Environment	Host URL
Production & UAT	https://pcmi-prod.fusionauth.io
The full OpenAPI Specification for this API can be found here

Parameters

In addition to the route, URL form encoded parameters must be supplied for the following keys:

Key	Example Value	Descripton
client_id	528aa7da-55d1-45e6-87db-9c383af930b3	Functionally like a username, but defined by the server
client_secret	hunter2	Functionally like a password
grant_type	client_credentials	Hard coded for now.
scope	a Scope String string	Defines whose data and what type of data you are trying to access

Scope String

The Scope string can be defined as:

target-entity:{TENANT_ID} target-entity:{AUDIENCE} target-entity:{AUDIENCE}

where TENANT_ID is the appropriate tenant Id (provided out of band), and AUDIENCE is one to many audience values (provided out of band)

Sample Request

POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&grant_type=client_credentials&scope={SCOPE}

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "access_token": "{ACCESS_TOKEN}",
  "expires_in": 3600,
  "scope": "{SCOPE}",
  "token_type": "Bearer"
}

Calling the APIs

Once you are authorized, and assuming you have the correct authorization / permissions, you may call the call the APIs.
To do this, you'll need to take the JWT Token and an API key and submit them with whatever payload the given API endpoint expects.

Getting an API Key

API keys currently are available upon request only.

Utilizing the Token

To utilize the token

The JWT token or Access token must be provided via standard Bearer Authorization Headers

The API Key must be provided via a header with the key x-api-key

Sample Request

GET /v1/someapi/ HTTP/1.1

Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
}

What is Authorization?#

How do I get Authorized?#

Get a Client Id and Secret#

Make the call to get a JWT Token#

Hosts#

Parameters#

Scope String#

Sample Request#

Sample Response#

Calling the APIs#

Getting an API Key#

Utilizing the Token#

Sample Request#

Sample Response#

What is Authorization?

How do I get Authorized?

Get a Client Id and Secret

Make the call to get a JWT Token

Hosts

Parameters

Scope String

Sample Request

Sample Response

Calling the APIs

Getting an API Key

Utilizing the Token

Sample Request

Sample Response