TokenEndpoint

Token Endpoint

POST request to /fhir/auth/token

The token endpoint is used to obtain access tokens. An access token must be provided as a bearer token with any request to an API.

The sequence for calling the token endpoint is different for Backend Services apps and Provider/Patient facing apps. Backend Services apps can call the token endpoint directly to obtain an access token, while aProvider/Patient facing app must first call the authorize endpoint to request and obtain consent from an end user.

Methods supported for authenticating apps against the Token endpoint.

Using a client secret, which requires you to provide your client ID and secret in a basic authorization header when calling the token API.
Using a JWKS (JSON Web Key Set). A JWT (JSON Web Token) is generated and signed with a public/private keypair by the caller and presented to the token endpoint. The call is authenticated if the JWT's signature can be verified using one of the app's public keys.
Using a proof key for code exchange, or "PKCE", requires you to generate your own secret for each token request that can be verified by our authorization server. PKCE is required by the token API for native or single-page browser apps that cannot securely store a client secret.

Client Secret Authentication

Your app will have a client secret associated with its client ID. This secret will be passed in a basic authorization header on every request to the token endpoint.

JWKS (JSON Web Key Sets)

Client-assertion JWT (JSON Web Token) authentication uses a public/private keypair to authenticate the caller to the token endpoint.

Requesting a token using the client assertion JWT method requires that you sign a JWT assertion using the private portion of a keypair associated with your app. This assertion is then provided to the token endpoint for authentication. The assertion JWT must contain the following claims:

Claim	Description
`aud`	Required. Fhir Base Url: https://fhir.mkoss.com/fhir
`exp`	Required. Expiration Time
`iss`	Required. Client Id of the client app.
`sub`	Required. Client Id of the client app.

PKCE

PKCE is required by our authorization server for native or single-page browser apps using Provider/Patient facing apps that cannot securely store a client secret.

To leverage PKCE for your app, please refer to Oauth 2 PKCE and RFC 7636

Input Parameters

Parameter	Description
`grant_type`	For Backend Services apps, the value is always client_credentials. For Patient/Provider facing apps, the value is authorization_code to initially request an access token, or the value is refresh_token to obtain a new access token from a refresh token.
`redirect_uri`	Required if grant_type is authorization_code. Your App's redirect uri
`code`	Required if grant_type is authorization code. The value is the code parameter returned by the authorize endpoint.
`code_verifier`	Required for token authentication using PKCE if grant_type is authorization_code and your app cannot securely store a client secret.
`scope`	App requested scopes, only valid for Provider/Patient facing apps.
`refresh_token`	Required if grant_type is refresh_token

Output Parameters

The token endpoint returns a JSON object.

access_token: JWT to be used as a bearer token in API requests
token_type: value is always "bearer"
expires_in: represents the lifetime of the access token in seconds
id_token: JWT containing information on the authenticated end user (Povider/Patient facing apps)
refresh_token: JWT used to obtain a new access token without requiring re-authentication by an end user (default expiration is 90 days)