Authentication

PDK supports the client credentials and authorization code flows defined in the OAuth 2.0 specification.

Client Credentials

The client credentials flow allows your application to access PDK without a user. Most integrations use this flow due to its simplicity.

• Users grant authorization by adding a permission in PDK using the email address assigned to your application. This permission acts as a service account within an organization and will not be affected by personnel changes.
• Tokens provide access to all organizations that have authorized your application. New tokens are obtained by providing your client_id and client_secret.
• Events are attributed to your application generally rather than to specific users.

Step 1: Authorize your application

In order to access a PDK organization, a user within that organization must add a permission for your application. In the animation below, the email address assigned to the application is pdk@example.com.

Step 2: Retrieve an ID token

You can now retrieve an ID token that provides access to all organizations that have authorized your application.

Request

POST https://accounts.pdk.io/oauth2/token HTTP/1.1
Authorization: Basic {{credentials}}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Parameter	Location	Type	Required	Description
credentials	Header	String	Yes	Base64-encoded credentials: {{client_id}}:{{client_secret}}.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token_type": "Bearer",
  "access_token": "NmQ5MWIzNm...Ve6g9Lpv4w",
  "id_token": "eyJhbGciOi...9PUxVsmQUQ",
  "expires_in": 300
}

Property	Type	Description
token_type	String	The token type. This will always be set to Bearer.
access_token	String	The access token. This token is not used.
id_token	String	An ID token. This token can be used to authenticate subsequent API calls.
expires_in	Integer	The number of seconds before the ID token expires.

Authorization Code

The authorization code flow allows your application to access PDK on behalf of a user. This flow is less common, but it's useful if your application needs to be able to distinguish between multiple API users within the same organization.

• Users grant authorization by entering their PDK credentials in a web view managed by your application.
• Tokens only provide access to organizations that are accessible to the authenticated user. New tokens are obtained by providing your client_id and client_secret along with a user-specific refresh_token.
• Events are attributed to specific users who authorize your application.

Step 1: Display the login page

In order to authenticate a specific user, your application must display a web view and load the PDK login page using the URL below.

https://accounts.pdk.io/oauth2/auth?client_id={{client_id}}&redirect_uri={{redirect_uri}}&scope={{scope}}&prompt=consent&response_type=code&state=abc123

Parameter	Location	Type	Required	Description
client_id	Query	String	Yes	Your client ID.
redirect_uri	Query	String	Yes	A URL-encoded redirect URI. This must match one of the redirect URIs registered for your application. Requests to add or remove redirect URIs should be emailed to integrations@prodatakey.
scope	Query	String	Yes	A list of scopes. Possible values include openid if a refresh token isn't needed or openid+offline_access if a refresh token is needed.
prompt	Query	String	Yes	If a refresh token is needed, then this parameter is required and its value must be set to consent.
response_type	Query	String	Yes	The response type. This value should be set to code.
state	Query	String	No	URL-encoded state information specific to your application.

Step 2: Retrieve the authorization code

After entering their credentials, users will be redirected back to your application according to the redirect URI. Your application can then retrieve the authorization code from the query string.

https://example.com/?code=YjU5MzEwNz...BcKeRZgC4A&state=abc123

Property	Type	Description
code	String	The authorization code.
state	String	URL-encoded state information specific to your application.

Step 3: Retrieve an ID token

You can now retrieve an ID token that provides access to all organizations that are accessible to the authenticated user.

Request

POST https://accounts.pdk.io/oauth2/token HTTP/1.1
Authorization: Basic {{credentials}}
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code={{code}}&redirect_uri={{redirect_uri}}

Parameter	Location	Type	Required	Description
credentials	Header	String	Yes	Base64-encoded credentials: {{client_id}}:{{client_secret}}.
grant_type	Body	String	Yes	The grant type. This value should be set to authorization_code.
code	Body	String	Yes	The authorization code.
redirect_uri	Body	String	Yes	A URL-encoded redirect URI. This must match the redirect URI used to obtain the authorization code.

Response

The response includes an ID token and a refresh token (if requested).

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token_type": "Bearer",
  "id_token": "eyJhbGciOi...DHuhSu7aEw",
  "expires_in": 300,
  "refresh_token": "Yzg4NzRjOW...wPVW5vKE1Q",
  "access_token": "Y2ViZjY0OD...e3n0RuJiEs"
}

Property	Type	Description
token_type	String	The token type. This will always be set to Bearer.
id_token	String	An ID token. This token can be used to authenticate subsequent API calls.
expires_in	Integer	The number of seconds before the ID token expires.
refresh_token	String	The refresh token. This token can be exchanged for a new user-scoped ID token. It never expires but can only be used once.
access_token	String	The access token. This token is not used.

Step 4: Use the refresh token

Once an ID token expires, a refresh token can be used to retrieve a new one.

Request

POST https://accounts.pdk.io/oauth2/token HTTP/1.1
Authorization: Basic {{credentials}}
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token={{refresh_token}}

Parameter	Location	Type	Required	Description
credentials	Header	String	Yes	Base64-encoded credentials: {{client_id}}:{{client_secret}}.
grant_type	Body	String	Yes	The grant type. This value should be set to refresh_token.
refresh_token	Body	String	Yes	The refresh token returned in the previous step.

Response

The response includes a new ID token as well as a new refresh token, which can be used again for perpetual access.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token_type": "Bearer",
  "id_token": "eyJhbGciOi...VrfKfscImA",
  "expires_in": 300,
  "refresh_token": "MWI2NmYxMW...aWajGjiaaW",
  "access_token": "YWRhNjQwNz...bPpSCXGHmg"
}

Property	Type	Description
token_type	String	The token type. This will always be set to Bearer.
id_token	String	The ID token. This token can be used to authenticate subsequent API calls.
expires_in	Integer	The number of seconds before the ID token expires.
refresh_token	String	The refresh token. This token can be exchanged for a new user-scoped ID token. It never expires but can only be used once.
access_token	String	The access token. This token is not used.