Authentication

Each account is provided with a client-id and client-secret. These keys are secret and should never be shared to any party other than the owner.

For security reasons

Do NOT store/use these credentials inside a publicly distributed mobile application
Do NOT store these credentials inside a github repository, not even a private one

A recommended good practice is to store these keys in a secure place, such as an environment variable or a password manager.

The SDK will never ask for the client-id and client-secret.

To use the SDK you will need to provide a temporary scoped token.

Generate a token

Authentication is provided through the standard OAuth2/OIDC protocol. To generate a token, you need to send a POST request to the token endpoint. Tokens expire after an hour. You may generate as many token as needed.

Scope

In this request you will need to provide a scope. This part is very important as it determine the access rights of the generated token. The scope is a space-separated list of rights.

Key	Status	Description
`openi`	mandatory
`su`	mandatory
`urn:zitadel:iam:org:project:id:272428514190297504:aud`	mandatory
role:`owner` or `restricted`	optional	As `owner` you can access to every data & actions As `restricted` you'll have limitations Default is `owner`
mount:`mountUid`	optional	If provided, will restrict actions to the specified mount. Doesn't affect owner rights

If mandatory scopes are not provided, the token will be generated but it won't have the required rights to perform any action.

Token request

The endpoint is urlencoded and the request will look like this:

Endpoint: POST https://auth.obh-mobility.com/oauth/v2/token

Content-Type : application/x-www-form-urlencoded

Data

Key	Value
`Content-Type`	`application/x-www-form-urlencoded`
`grant_type`	`client_credentials`
`scope`	`openid sub urn:zitadel:iam:org:project:id:272428514190297504:aud role:<role> [mount:<mountUid>]`
`client_id`	{your client id}
`client_secret`	{your client secret}

Curl Example: Owner

curl --request POST \
  --url https://auth.obh-mobility.com/oauth/v2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=openid profile sub urn:zitadel:iam:org:project:id:272428514190297504:aud role:owner' \
  --data client_id=fake-company-sandbox \
  --data client_secret=QftVrBgfBtrPrRPaz7pQUHDl6wfQ80hnVmtodRtgty6reDjNjFosg1YnATtYimVWo

Curl Example: Restricted

curl --request POST \
  --url https://auth.obh-mobility.com/oauth/v2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=openid profile sub urn:zitadel:iam:org:project:id:272428514190297504:aud role:restricted mount:BgfBtrPrRPaz7pQU' \
  --data client_id=fake-company-sandbox \
  --data client_secret=QftVrBgfBtrPrRPaz7pQUHDl6wfQ80hnVmtodRtgty6reDjNjFosg1YnATtYimVWo

More information

We use Zitadel as our identity provider. It follows the OpenID Connect standard. Zitadel provides a variety of authentication methods, especially for token generation.

You can find the list of endpoints and more information on the Zitadel endpoints page.

JWT Private key

If you feel technically confident, we can provide you a JWT Private key to generate your tokens. It's a more secure and faster way to generate and introspect tokens (by far).

Questions

What happens if I share my client-id and client-secret?

People will be able to use account at will. They will be able to access all data and perform all actions, including dissociating any mount and get them for them self.

What happens if I share an owner token?

If end users receive an owner token on their phone, there are no ways to prevent them from using it. They will be able to access all data and perform all actions for the lifetime of the token.

My client-secret was leaked, what should I do?

You should immediately email us at support@obh-mobility.com. We will invalidate your client-secret and provide you with a new one.

If possible, contact your account manager by phone to expedite the process.

Any credential sent to a front end has to be considered leaked.

Use cases

You will find below several examples of use cases for different scenarios.

Mount installation

We recommend storing the mount UID when you install a mount on a bike, as it will be required to generate a token with the mount:<mountUid> scope.

Maintenance

In this case, a maintainer will need to access all mounts to perform maintenance tasks.

Rental Application

Here is a case with a mobile application that allows end users to rent a bike.

Hack through a corrupted mobile device

When the access token is properly scoped, a hack would lead to nothing more than what's intended in the first place.