Authentication

Authentication is a vital aspect of interacting with the Semble GraphQL Public API. It ensures the security and integrity of your data. Depending on your use case, we provide two methods of authentication: token authentication and user authentication.

Environments

Use the GraphQL endpoint that matches the environment where you created your credentials. Tokens are environment-scoped: a sandbox token is only valid on the sandbox host, and a production token is only valid on the production host.

Environment	GraphQL endpoint
Production	https://open.semble.io/graphql
Sandbox	https://open.sandbox.semble.io/graphql

Examples in this documentation use the production URL. When you are working against sandbox, replace it with https://open.sandbox.semble.io/graphql.

warning

Wrong environment looks like an expired token

Sending a sandbox credential to https://open.semble.io/graphql (or a production credential to sandbox) is rejected with a message such as "Your session expired. Sign in again." — the same wording used for an expired or revoked token. If a newly created token fails immediately, confirm you are calling the matching environment endpoint before regenerating credentials.

Token Authentication

Token authentication is used when your users don't need to authenticate themselves individually. In this scenario, you use a token that is generated in the Semble application.

Settings API credentials are the recommended authentication method for server-side integrations, including availability mutations such as createAvailability. You do not need signIn for programmatic availability management.

When a Settings credential creates or updates availability, createdBy and lastUpdatedBy may be the credential ID rather than a user ID, because Settings credentials are not bound to a person.

Follow the steps below to obtain and use the token:

1. Obtain the Token:

   • Open the Semble application.
   • Navigate to the Settings section.
   • Generate your unique token.

tip

Tokens are very flexible and will control what the API user has access to. For example, you can generate a token that only has access to the patient query, or you can generate a token that has access to bookings but not patients. You can also generate a token that has access to everything.

2. Use the Token:
   • Once you have the token, include it in your HTTP requests using the x-token header. Here's are examples using curl, javascript, and Python to send a POST request to open.semble.io, querying a patient's firstName and email.

curl

curl -X POST https://open.semble.io/graphql \
-H "Content-Type: application/json" \
-H "x-token: YOUR_TOKEN" \
-d '{
  "query": "query { patient(id: \"1\") { firstName email } }"
}'

Javascript

To perform HTTP requests in JavaScript, you can use the node-fetch library. If it's not installed, you can add it with npm install node-fetch.

const fetch = require('node-fetch');

const query = `
  query {
    patient(id: "1") {
      firstName
      email
    }
  }
`;

fetch('https://open.semble.io/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-token': 'yourtoken',
  },
  body: JSON.stringify({ query }),
})
  .then((res) => res.json())
  .then((res) => console.log(res.data));

Python

Python's requests library is widely used for making HTTP requests. If it's not installed, you can add it with pip install requests.

import requests
import json

query = """
  query {
    patient(id: "1") {
      firstName
      email
    }
  }
"""

headers = {
    'Content-Type': 'application/json',
    'x-token': 'yourtoken',
}

response = requests.post(
    'https://open.semble.io/graphql',
    headers=headers,
    data=json.dumps({"query": query})
)

print(response.json())

Replace YOUR_TOKEN with your actual token obtained from the Semble application, and id with the actual patient ID.

User Authentication

User authentication is used when your users need to authenticate individually. In this case, you use the signIn mutation, which returns a short-lived token, valid for 12 hours.

Here's an example of performing the signIn mutation:

curl

Copy code
curl -X POST https://open.semble.io/graphql \
-H "Content-Type: application/json" \
-d '{
  "query": "mutation { signIn(email: \"user@example.com\", password: \"password\") { token } }"
}'

Javascript

const fetch = require('node-fetch');

const mutation = `
  mutation {
    signIn(email: "user@example.com", password: "password") {
      token
    }
  }
`;

fetch('https://open.semble.io/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: mutation }),
})
  .then((res) => res.json())
  .then((res) => console.log(res.data));

Python

import requests
import json

mutation = """
  mutation {
    signIn(email: "user@example.com", password: "password") {
      token
    }
  }
"""

headers = { 'Content-Type': 'application/json' }

response = requests.post(
    'https://open.semble.io/graphql',
    headers=headers,
    data=json.dumps({"query": mutation})
)

print(response.json())

Replace "user@example.com" and "password" with the user's actual email and password. The server will return a JSON object that includes a token field.

Once you have obtained the token, include it in the x-token header in your HTTP requests as shown in the token authentication example.

Remember to keep your tokens secure. Do not share them publicly. If a token is compromised, you should revoke it immediately.

In the next section, we will explore how to use these tokens to make requests to the Semble GraphQL Public API.