Skip to content

OAuth Client Registration

For managing developer related information there is a Tapkey Integrator Portal. In this portal you can extend your existing owner account created via Tapkey Web Portal that will be created when registering your first lock with Tapkey Web Portal.

Don't have a lock?

You can still create an owner account without registering a lock. Go to the Tapkey Integrator Portal on https://portal.tapkey.io and make sure you are logged in with the desired user. Afterwards expand the drop down menu in the navigation drawer saying "Locking systems". This will reveal a button stating "Create own locking system". Use it to create a new owner account and you are good to go.

You can register OAuth clients using the self-service registration page on Tapkey Integrator Portal.

Authorization Code

  1. Go to the OAuth Clients page on portal.tapkey.io.
  2. Click on the plus button in the lower right corner.
  3. Enter a name of your choice in the Client name input. This is used to identify the OAuth client and can be changed later.
  4. Choose "Authorization Code" from the Grant type input.
  5. Choose "With client secret" from the Authorization type input.
  6. Enter the location of your client's logo in the Logo URL input. The logo will be shown to Tapkey users when they are asked to grant your application access to their Tapkey account. A square PNG works best.
  7. Enter any required redirect URIs, separated by comma, in the Redirect URIs input.
  8. Enter any required allowed CORS origins, separated by comma, in the Allowed CORS origins input.
  9. Enter any required post-logout URIs, separated by comma, in the Post-logout URIs input.
  10. Choose the required scopes from the Permissions section. The scopes required are listed along every operation in the API documentation.
  11. Click on the check mark button in the lower right corner to create the new OAuth client.
  12. A dialog with the client's secret appears. Note the secret and store it at secure place. This is the only time the secret is displayed.

Warning

Although multiple values can be entered into the Redirect URIs, Allowed CORS origins and Post-logout URIs inputs, it is strongly discouraged to use clients pointing to localhost in production. Keep testing and production environments separated by using multiple OAuth clients.

Secret rollover

In order to gracefully replace the client's secret, the OAuth client registration form has a secret rollover function.

  1. Go to the OAuth Clients page on portal.tapkey.io.
  2. Choose the OAuth client from the list.
  3. Click on the secret rollover button in the secret reset section.
  4. Choose an expiration time in minutes for any previous secrets. Any previous secrets will stop working after that time.
  5. Start secret rollover by clicking the button at the bottom of the dialog.

Authorization Code with PKCE

  1. Go to the OAuth Clients page on portal.tapkey.io.
  2. Click on the plus button in the lower right corner.
  3. Enter a name of your choice in the Client name input. This is used to identify the OAuth client and can be changed later.
  4. Choose "Authorization Code" from the Grant type input.
  5. Choose "With PKCE" from the Authorization type input.
  6. Enter the location of your client's logo in the Logo URL input. The logo will be shown to Tapkey users when they are asked to grant your application access to their Tapkey account. A square PNG works best.
  7. Enter any required redirect URIs, separated by comma, in the Redirect URIs input.
  8. Enter any required allowed CORS origins, separated by comma, in the Allowed CORS origins input.
  9. Enter any required post-logout URIs, separated by comma, in the Post-logout URIs input.
  10. Choose the required scopes from the Permissions section. The scopes required are listed along every operation in the API documentation.
  11. Click on the check mark button in the lower right corner to create the new OAuth client.

Warning

Although multiple values can be entered into the Redirect URIs, Allowed CORS origins and Post-logout URIs inputs, it is strongly discouraged to use clients pointing to localhost in production. Keep testing and production environments separated by using multiple OAuth clients.

Client Credentials

  1. Go to the OAuth Clients page on portal.tapkey.io.
  2. Click on the plus button in the lower right corner.
  3. Enter a name of your choice in the Client name input. This is used to identify the OAuth client and can be changed later.
  4. Choose "Client Credentials" from the Grant type input.
  5. Check Administrator of this locking system to assign administrator permission to this client. (Only possible when you are an owner of this locking system.)
  6. Choose the required scopes from the Permissions section. The scopes required are listed along every operation in the API documentation.
  7. Click on the check mark button in the lower right corner to create the new OAuth client.
  8. A dialog with the client's secret appears. Note the secret and store it at secure place. This is the only time the secret is displayed.

Grant access to resources

  1. Go to the OAuth Clients page on portal.tapkey.io.
  2. Choose the OAuth client from the list.
  3. Copy the client's IAM service account email (<id>@iam.serviceaccount.tapkey.com).
  4. Go to the settings page and click the plus button in the lower right corner to add a new administrator.
  5. Click Add smartphone user to add new user with email address from step 3.
  6. Select created contact and in the next step select Administrator role and confirm.

Secret rollover

In order to gracefully replace the client's secret, the OAuth client registration form has a secret rollover function.

  1. Go to the OAuth Clients page on portal.tapkey.io.
  2. Choose the OAuth client from the list.
  3. Click on the secret rollover button in the secret reset section.
  4. Choose an expiration time in minutes for any previous secrets. Any previous secrets will stop working after that time.
  5. Start secret rollover by clicking the button at the bottom of the dialog.

Token Exchange

Tip

An identity provider must be registered before a client with Token Exchange grant type can be created.

  1. Go to the OAuth Clients page on portal.tapkey.io.
  2. Click on the plus button in the lower right corner.
  3. Enter a name of your choice in the Client name input. This is used to identify the OAuth client and can be changed later.
  4. Choose "Token Exchange" from the Grant type input.
  5. Select the desired identity provider from the Identity provider input.
  6. Choose the required scopes from the Permissions section. The scopes required are listed along every operation in the API documentation.
  7. Click on the check mark button in the lower right corner to create the new OAuth client.