Authentication (1.0.0)

Download OpenAPI specification:Download

Authentication for access to Commure APIs.

Authorization Endpoint

get /auth/authorize
https://api-{tenant_id}.developer.commure.com/auth/authorize

This endpoint allows clients to initiate the OpenID Connect/SMART App Launch authentication process. The Commure Authentication API supports the OpenID Connect Authorization Code, Implicit, and Hybrid flows, combined with the SMART EHR launch sequence and SMART standalone launch sequence.

To initiate the authentication process, clients should navigate the user to this endpoint, which will authenticate the user via single sign-on (SSO), typically using an SSO provider configured by a hospital. After the SSO process completes, the user will be redirected to the URL specified in the redirect_uri query parameter. This callback will include query parameters that depend on the requested response_type, as defined by OpenID Connect. If an error occurs, the user will be forwarded to the redirect_uri with an error response.

Authorizations:
query Parameters
response_type
required
string <space-delimited>
Example: response_type=code

Specifies the desired authentication flow. This parameter is a space-delimited string that supports any combination of the following values:

The most common and secure usage is to pass the value code, which indicates that the client wishes to receive a single-use authorization code at its redirect_uri, which can then be exchanged for an access token using the Token Endpoint.

Alternatively, the values token or token id_token (if using the openid scope) indicate that the client wishes to receive an access token and optional OpenID Connect ID token at its redirect_uri utilizing the Implicit flow. Finally, combinations such as code token id_token may also be used for the Hybrid flow.

For security reasons, the Implicit and Hybrid flows may not be enabled in all Commure Platform environments.

client_id
required
string
Example: client_id=98d4fa023300a6d5d22bbc3dfa7c67b06947331d547e636e

Client identifier provided by Commure.

redirect_uri
required
string <url>
Example: redirect_uri=https://my-app.example.com/auth/callback

The URL to which the user should be navigated following completion or failure of the SSO process. For security reasons, this URL must be pre-configured with the Commure Platform; otherwise, the user will be presented with an error message.

scope
required
string <space-delimited>
Example: scope=openid profile email phone address fhirUser

Specifies the scope of the access request. This parameter is a space-delimited string that supports any combination of the following values:

  • openid: Requests that the Token Endpoint return an OpenID Connect ID token.
  • profile: Requests that the OpenID Connect ID token contain the user's default profile claims (name, family_name, given_name, etc.).
  • email: Requests that the OpenID Connect ID token contain the email claim.
  • phone: Requests that the OpenID Connect ID token contain the user's phone number.
  • address: Requests that the OpenID Connect ID token contain the user's address.
  • fhirUser: Requests that the OpenID Connect ID token contain the SMART App Launch fhirUser claim.
state
required
string
Example: state=E53pRBBCBkyJAlKkN8WA3Gf148gT2MG4EhGtvqg+2v0=

Opaque value used for passing state to the redirect_uri and mitigating session fixation/cross-site request forgery (CSRF) vulnerabilities. Clients not using the <CommureSmartApp/> React component should include a cryptographically secure pseudorandom value in the state parameter for each authentication request and verify this value at the specified redirect_uri, as described in Section 10.12 of RFC 6749.

nonce
string
Example: nonce=byWNuPqvwyTsS1HXYui68OlylBOHNeaMrLGDzCYFe2A=

Value used for mitigating ID token replay vulnerabilities. If the openid scope is requested, this parameter will be included as the nonce value in the OpenID Connect ID token. Clients not using the <CommureSmartApp/> React component should provide a cryptographically secure pseudorandom nonce value for each authentication request and verify that the nonce contained in the ID token returned by the Token Endpoint (or passed to the redirect_uri in the Implicit or Hybrid flows) matches this value.

code_challenge
string
Example: code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

Proof Key for Code Exchange (PKCE) challenge for mitigating authorization code interception attacks. Clients without a client secret are strongly encouraged to use PKCE when utilizing the Authorization Code flow.

code_challenge_method
string
Value: "S256"
Example: code_challenge_method=S256

Proof Key for Code Exchange (PKCE) challenge method. For security reasons, the Commure Authentication API only supports the S256 (SHA-256) challenge method.

launch
string
Example: launch=9b2b8c8f-284e-4d93-bcd2-f30a00c65d99

Opaque value issued by the EHR during the SMART EHR launch sequence. If omitted, the SMART standalone launch sequence is used.

aud
string <url>
Example: aud=https://fhir-ehr.example.com/dstu2/14c262be-9e15-470c-bc80-70a1ee97173f

URL of the EHR FHIR server that should be used to authenticate the user. This URL must be pre-configured with the Commure Platform. This parameter is required for the SMART EHR launch sequence and is typically used alongside the launch parameter. However, it may optionally be specified for the SMART standalone launch sequence as well.

Responses

303

Redirect user to single sign-on (SSO) provider or error callback

400

Invalid client_id or redirect_uri

Response samples

Content type
text/plain
Copy
Invalid client_id `my_app`

Token Endpoint

post /auth/token
https://api-{tenant_id}.developer.commure.com/auth/token

This endpoint allows clients to retrieve access tokens for use in authenticated requests to Commure APIs.

The following grant types are supported:

  • Authorization Code: used for exchanging a single-use authorization code sent to a client's redirect_uri for an access token and optional refresh token.
  • Client Credentials: used by clients with an associated client secret for which the Client Credentials grant is enabled within the specific Commure Platform environment to exchange their client credentials for an access token and optional refresh token. This grant should only be used when making Commure API requests that cannot reasonably be associated with an individual user. Otherwise, the Authorization Code grant should be used.
  • Refresh Token: used for exchanging a refresh token for a new access token and optional refresh token.
Authorizations:
header Parameters
Authorization
string
Example: Basic OThkNGZhMDIzMzAwYTZkNWQyMmJiYzNkZmE3YzY3YjA2OTQ3MzMxZDU0N2U2MzZlOlNlYy14ajJRbXdFSjBHZUZqWDY3XzgtX3JaNDR6STQ9LWNlUw==

If the client has an associated client secret, this header is the preferred method for performing client authentication. The contents of this header should follow the format base64(urlEncode(client_id):urlEncode(client_secret)) as described in Section 2.3.1 of RFC 6749. If the Authorization header is provided, the client_id and client_secret body parameters should be omitted.

Request Body schema: application/x-www-form-urlencoded

Grant type and corresponding parameters.

Example: grant_type=authorization_code&code=Sec-KB5xNSx2kAh66LzyAPncuFI%2BniA%3D-ceS&redirect_uri=https%3A%2F%2Fmy-app.example.com%2Fauth%2Fcallback&client_id=98d4fa023300a6d5d22bbc3dfa7c67b06947331d547e636e

One of
  • Authorization Code
  • Client Credentials
  • Refresh Token
grant_type
required
string
Value: "authorization_code"

Value must be set to authorization_code.

code
required
string

Authorization code passed to the redirect_uri (specified at the Authorization Endpoint). Each code can only be used once.

redirect_uri
required
string <url>

Must match the redirect_uri passed to the Authorization Endpoint.

code_verifier
string

Proof Key for Code Exchange (PKCE) verifier for mitigating authorization code interception attacks. This parameter is required if the code_challenge parameter was supplied to the Authorization Endpoint. Clients without a client secret are strongly encouraged to use PKCE when utilizing the Authorization Code flow.

client_id
string

Client identifier provided by Commure. This value must match the client_id passed to the Authorization Endpoint. This parameter is required unless the Authorization header is provided.

client_secret
string

Client secret, if one was provided by Commure. The Authorization header is preferred over using this parameter.

Responses

200

Token Response

400

Bad Request

401

Unauthorized

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "access_token": "Sec-2IvL75C7e2WKkd3eckxHgijd5sk-ceS",
  • "token_type": "bearer",
  • "expires_in": 3600,
  • "refresh_token": "Sec-DQz8FM+Dh1ft6kY7VVZGSyeX3jA-ceS",
  • "scope": "openid profile email fhirUser",
  • "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjliMGQ3YWRmMGE3Zjk3Y2ViNjhhYjMwZGNjODA0ZGRiYjQxZmY1NDRlNTU3ZWVkNGZhZmZlN2U4Zjk5Y2RlM2IifQ.eyJpc3MiOiJodHRwczovL2FwaS0xMjM0NS5kZXZlbG9wZXIuY29tbXVyZS5jb20vYXV0aCIsImF1ZCI6WyI5OGQ0ZmEwMjMzMDBhNmQ1ZDIyYmJjM2RmYTdjNjdiMDY5NDczMzFkNTQ3ZTYzNmUiXSwiZXhwIjoxNTg0MTI5MTA1LCJpYXQiOjE1ODQxMjg4MDUsImF0X2hhc2giOiJnQTh1UVp6NTc4M1l3Qnl5WGlyYlNnIiwic3ViIjoiNTBlZjQ3YzktNjdjNi00ODEzLWE2NzctZTY5ZDU4NzM5MjAxIiwibmFtZSI6IkFsZXggR2lsbW91ciIsImdpdmVuX25hbWUiOiJBbGV4IiwiZmFtaWx5X25hbWUiOiJHaWxtb3VyIiwiZmhpclVzZXIiOiJodHRwczovL2FwaS0xMjM0NS5kZXZlbG9wZXIuY29tbXVyZS5jb20vYXBpL3YxL3I0L1ByYWN0aXRpb25lci80OWJiMDQ0MS1mZGQ4LTRiNTQtYjA5NS04MjFjYjNmMjdjMzgifQ.Idmod4BEogJKqTohr3J0XpMNmj7c21uDqfIiL-DdowSXLa9TQ2e-YaaW_dWEIIyq95aZcP-U4w4_v4NR1QPQDNd0_Az2QzaWl5UGZ8tqJIHmtN7EVsgJ5QNk-Fz_VJ0A0BoAvsXdrKZHY2N3L_5zd3W1Ph5Jh_THaiUDFAOzg5z_JVE3x-b_EbohRogONn9gy6MGS7uVeozzZYFQbBimCPkpejCLNAlmBWh4WRgvPKeIo66vKLfG3D8lsry2a1BLHqWWf3Qxe4g2WbwCEOKRkzh-I1Vy5zR8QzFEFcIXqq0E2vJs11GNAV1AQP3v-ScLNPU_CKKQ7hFXqU6lwzNuXQ",
  • "patient": "4d79da29-8302-422c-9dcf-2d6ee4c71f28"
}

Public Keys

get /auth/jwks
https://api-{tenant_id}.developer.commure.com/auth/jwks

This endpoint returns a JSON Web Key Set (JWKS) that clients can use to verify OpenID Connect ID tokens issued by the Commure Authentication API.

Authorizations:

Responses

200

JSON Web Key Set

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "keys":
    [
    ]
}

OpenID Connect Provider Metadata

get /auth/.well-known/openid-configuration
https://api-{tenant_id}.developer.commure.com/auth/.well-known/openid-configuration

OpenID Connect Discovery metadata describing provider configuration.

Authorizations:

Responses

200

OpenID Connect Provider Metadata

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

SMART App Launch Configuration

get /api/v1/r4/.well-known/smart-configuration
https://api-{tenant_id}.developer.commure.com/api/v1/r4/.well-known/smart-configuration
Authorizations:

Responses

200

SMART App Launch Configuration

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token_endpoint_auth_methods":
    [
    ],
  • "scopes_supported":
    [
    ],
  • "response_types_supported":
    [
    ],
  • "capabilities":
    [
    ]
}

UserInfo

get /auth/userinfo
https://api-{tenant_id}.developer.commure.com/auth/userinfo

This endpoint returns information about the authenticated user in the form of OpenID Connect claims. The returned claims depend on the scope values associated with the access token as well as the information provided by the single sign-on (SSO) provider and electronic health record (EHR). Even when the relevant scope has been requested, clients should expect that any claim except aud (audience client ID) and sub (subject ID) may be omitted from the response.

Responses

200

UserInfo Response

401

Unauthorized

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Logout

get /auth/logout
https://api-{tenant_id}.developer.commure.com/auth/logout

This endpoint logs out the authenticated user.

Responses

200

Success

401

Unauthorized

Response samples

Content type
text/plain
Copy