Accessing the API

A PhenoTips root endpoint varies based on your local configuration. The protocol, host, port number and URL path may be unique to either of your production and staging deployments of PhenoTips.

http://acme.genetics:8443/phenotips/
https://phenotips.institution.edu:443/

Authenticating with the API

📘
Which API authentication scheme applies to you?
The API authentication scheme for accessing your PhenoTips deployment depends on your user management configuration and deployment environment. If an on-premises PhenoTips deployment manages your users, read the content under PhenoTips User Management (On-Premises Deployment). If a cloud-based PhenoTips deployment manages your users, read the content under PhenoTips User Management (Cloud Deployment). If your organization hosts your own user management, read the content under Hosted User Management.

PhenoTips User Management (On-Premises Deployment)

When an on-premises PhenoTips deployment manages your users, the PhenoTips API requires HTTP Basic authentication. The username and password combination must be base64 encoded. You can provide your username and password combination via an authorization HTTP header, or, you can save a PhenoTips user session cookie to a local file. You can then use the saved session cookie to authenticate subsequent requests to any PhenoTips endpoint.

curl -i -H "Authorization: Basic shjvJvcjhy6SampleSc7v3Credentials35juVKf8fgj5yf" http://acme.genetics:8443/phenotips/rest/patients/P0000002

PhenoTips User Management (Cloud Deployment)

When a cloud-based PhenoTips deployment manages your users, the PhenoTips API requires a bearer token acquired via an OAuth 2.0 Password Grant. Contact your PhenoTips representative to obtain more information about this API authentication scheme.

Client-hosted User Management (Cloud Deployment)

When your organization hosts your own user management, HTTP Basic and API key credentials are needed to access the PhenoTips API. The HTTP Basic username and password combination must be base64 encoded, included as an authorization HTTP header and belong to a service account. Contact your PhenoTips representative to obtain this service account credential.

The API key must be included as an HTTP header named X-Gene42-Secret. Contact your PhenoTips representative to obtain a key.

curl -i -H "Authorization: Basic shjvJvcjhy6SampleSc7v3Credentials35juVKf8fgj5yf"-H "X-Gene42-Secret: UBT6gf7fHu6T4HgvSample8Hg2Key9ByvcR6d65c5jkc" https://acme.genetics.phenotips.com/rest/patients/P0000001