API Authentication

Generally speaking, you will not need to authenticate to gain access to PharmGKB data. The exception to this rule is PharmGKB's variant and clinical annotations.

To authenticate, you must have an active PharmGKB account. You can register for one here.

OAuth Based Authentication

The API will grant you authorization based on the OAuth bearer token you provide with every request in the Authorization header.

To get the token, you can authenticate your identity with either your username and password or your API Key.

Authenticating with Username/Password

With JSON:

> curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
  "username": "your_username",
  "password": "your_password"
  }' 'https://api.pharmgkb.org/v1/auth/oauthSignIn'

With form input:

> curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' 
  -d 'username=your_username&password=your_password' 
  'https://api.pharmgkb.org/v1/auth/oauthSignIn'

Authenticating with API Key

To do this, you'll need to get your API Key and Secret.

Then you'll need to base64 encode the combination (API_KEY:API_SECRET) and pass the encoded data in the Authorization header.

> curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' 
  -H 'Authorization: Basic YOUR_ENCODED_TOKEN' 
  'https://api.pharmgkb.org/v1/auth/oauthToken'

Using the Bearer Token

Upon successful validation, you will get a response that looks like:

{
  "access_token": "eyJhbGdi6i8IUza1NiIPInR5cCI6IkpXVCJ9...xrY0",
  "token_type": "Bearer",
  "expires_in": 3600
}

You can now use this bearer token in all future API requests in the Authorization header:

> curl -X GET -H 'Authorization: Bearer YOUR_BEARER_TOKEN' 
  'https://api.pharmgkb.org/v1/data/gene/PA264'