Skip to main content

Authentication

Calls to the Connect Mesh Web API need to be authenticated either with Bearer Tokens. This can either be done by using a Tokens created on the developer section or by using OAuth2 to get a Access Token on behalf of another user.

Tokens​

Tokens allow you to call the Web API for the user who created the token. To cre Tokens that are created manually are of the format CMC_<TokenId>_<SecretKey> and allow access to all Web API endpoints limited to the user that created the token. E.g. all networks of this user can be controlled.

Creating a token​

Visit the developer section in your Connect Mesh Cloud Account in order to create a Token.

  • Click on Create a new token
  • Give your token some meaningful name in order for easy future identification.
  • Additionally you have to set an expiration date. You can use the offset helper to set it to a specific time from now.
caution

When you create the token, the token will be displayed only once. Make sure to save it somewhere for further usage otherwise you will have to create a new one.

OAuth2​

If you want to be able to control the networks for the users of your application, you can use the OAuth client mechanism instead. This allows you to ask your users to link their Connect Mesh Cloud Account to your application and perform calls to the Web API on their behalf.

Creating a client​

Visit the developer section in your Connect Mesh Cloud Account in order to create a Token.

  • Click on Create a new client
  • Give your client some meaningful name in order for easy future identification as well as a description. This will be displayed to the user when linking the service.
  • Add the redirect URIs (comma seperated) that are allowed as callback urls on user consent or rejection of the linking request.
  • Choose which permissions you would like to request. Read permissions for Get request, write permissions for Post requests and offline_access if you would like to be able to renew the Access Tokens (e.g. keep using a users network instead of performing a one off operation on the users network).
caution

When you create the client, the secret will be displayed only once. Make sure to save it somewhere for further usage otherwise you will have to create a new one.

Try it out​

  • Create a new client using following values:
    • name: OAuthdebugger
    • info: OAuth Test
    • redirect url https://oauthdebugger.com/debug
    • Permissions: check read, write and offline_access save the client secret.
  • Visit oauthdebugger.com and add the following entries
    • Authorize URI: https://cloud.connect-mesh.io/oauth2/auth
    • Redirect URI: https://oauthdebugger.com/debug
    • Client ID: The id of the just created client
    • Scope: read,write,offline_access
    • Response type code
  • Click Send request should redirect you to a screen where you can accept or reject the linking request
  • Accepting the request will result in an Authorization code
  • This Authorization code needs to used to get a user token. When building an application you should preferably use some library that will handle this for you but to try it out manually you will have to
  • Send a POST request to the token endpoint as followed:
# Authorization header is a base64 encoding of client_id:client_secret
curl --request POST https://cloud.connect-mesh.io/oauth2/token \
--header "Authorization: Basic <base64 encoded client_id:client_secret>" \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "Accept: application/json" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=<Authorization code>" \
--data-urlencode "redirect_uri=https://oauthdebugger.com/debug" \
--data-urlencode "client_id=<Client Id>" \
--data-urlencode "scope=offline_access read write"

This will give you back a Refresh Token and an Access Token. The access token can be used the same way as a normal Token to authenticate your Web API calls. The refresh token can be used to renew the access token on expiration.

  • To exchange the refresh token for a new access token
curl --request POST https://cloud.connect-mesh.io/oauth2/token \
--header "Authorization: Basic <base64 encoding of client_id:client_secret" \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "Accept: application/json" \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "refresh_token=<Refresh token>" \
--data-urlencode "redirect_uri=https://oauthdebugger.com/debug" \
--data-urlencode "client_id=oauthdebugger" \
--data-urlencode "scope=offline_access read write"