API Authentication

Smartmate authentication is built on top of the OpenID Connect / OAuth2 standard protocols.

Setting up authentication for your application requires the following steps:

  1. Add a new client

  2. Authenticate from your application using an OpenID Connect library

  3. Get an access token and use it for making requests

Choosing between public or confidential client

Add a new client

To allow your application to connect to Smartmate, you should create a new Auth Client. Smartmate supports two types of clients: public and confidential.

To add a new client:

  • Choose whether you want it to be public or confidential.

  • If public, set the Valid Redirect URIs.

  • If confidential, copy the client id and secret and store them in secure places. Anyone with these credentials will have access to your services.

  • Set the client permissions.

Public Client

A public client does not have a secret. It is useful for allowing users to log into Smartmate from your web applications.

If your client is public, you will need to define its Valid Redirect URIs. These are URIs the browser can redirect to after a successful login or logout. Simple wildcards are allowed such as http://example.com/*.

Confidential Client

A confidential client has a secret, which must be used to initiate a login. It is useful for backend services.

If your client is confidential, you will get a client id and secret that you can use to perform operations in the system.

Note

Currently, creating auth clients is limited to the Enterprise edition.

Authenticate from your application using an OpenID Connect library

Keycloak Adapters

Smartmate authentication is built on top of Keycloak, thus we recommend to use the Keycloak client adapters.

When connecting to Smartmate, using a Keycloak adapter, you will need the following information:

OpenID Connect Relying Party Libraries

If there is no a Keycloak adapter available for your preferred language, framework or platform, you can always use any OpenID Connect Relying Party (RP) library instead.

When using a Relying Party library, additional to the client id and secret that you got in the previous step, you might need the following endpoints:

For all the endpoints, make sure to replace YOUR-WORKSPACE with your workspace id.

Getting and using access tokens

After successfully configuring the OpenID Connect library, you will be able to request access tokens for your application. You should send the token in the Authorization header for all the requests made to Smartmate.

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TOKEN" \
  --data '{ "query": "{ apps { name } }" }' \
  https://YOUR-WORKSPACE-ws.apps.smartmate.io/v1/graphql

Make sure to replace TOKEN with a valid access token and YOUR-WORKSPACE with your workspace id.