Authentication

Requests to the Clinical API require an authorization token. In order to authenticate requests, include this token in the authorization header of any request being made. If the token is invalid or the token doesn't have the correct permissions, you will get an error.

This token can either be a Machine to Machine Access Token or a User Access Token.

Machine to Machine Token

Each Photon organization has one Machine to Machine Token to enable their backend to have programmatic access to the Photon API. This M2M Token can be used to generate Access Tokens to hit the Photon API.

You can get your Machine to Machine token in the settings page of the photon app.

After retrieving an Access Token, you can hit the Photon API. This token has access to complete all actions except write prescriptions, as prescriptions can only be written by authorized providers.

Getting an Access Token

In order to get an Access Token, you must execute a client credentials exchange described below.

Request

curl \
  https://auth.neutron.health/oauth/token \
  --request POST \
  --header "content-type: application/json" \
  --data @- << EOF
{
  "client_id":"YOUR_CLIENT_ID",
  "client_secret":"YOUR_CLIENT_SECRET",
  "audience":"https://api.neutron.health",
  "grant_type":"client_credentials"
}
EOF

curl \
  https://auth.photon.health/oauth/token \
  --request POST \
  --header "content-type: application/json" \
  --data @- << EOF
{
  "client_id":"YOUR_CLIENT_ID",
  "client_secret":"YOUR_CLIENT_SECRET",
  "audience":"https://api.photon.health",
  "grant_type":"client_credentials"
}
EOF

Response

{
	"access_token":"...",
	"scope":"read:patient write:patient read:prescription read:order write:order",
	"expires_in":86400,
	"token_type":"Bearer"
}

That's it! Now that the application has an access_token, it’s possible to make authorized calls to the Photon API.

User Access Token

User Access Tokens are generated with specific permissions according to the roles of a logged in user. Only providers who have been authorized can be assigned the write:prescription permission.

If you're calling Photon APIs from your frontend, you will need to authenticate a user and pass a token in a header with each request.

While the APIs to authenticate with auth.photon.health can be called by clients, it's much easier to use Elements which handle all of the SSO and authentication redirects.