To execute calls to the Cloud API a Bearer authentication is needed to be send in each request.
A bearer token can be requested by using the Authorization Code Grant of OAuth 2.0.
The steps for authentication are listed below:
For this example a randomly generated client id and client secret are used:
client_id: 9fc9e786-2069-4810-b4c0-618ae54de882 client_secret: 7598c79cc4370b8e1e84cab937822b7992876688d43a0865040fc02768f7ad1d
The following redirect url is registered for this client:
https://redirecturl.com/handleOauthResponse.php
You need to request the client data for your company by contacting DoorBird.
The client secret should never be exposed or used in code visible for users (do not include it in apps / frontend of websites / JavaScript) .
The application which should use the API displays the following page in a web browser:
authorize?response_type=code&client_id=9fc9e786-2069-4810-b4c0-618ae54de882&scope=deviceViewer&state=mystate&redirect_uri=https://redirecturl.com/handleOauthResponse.php
The parameter scope can be deviceViewer or deviceAdmin, depending on whether the user has to login with the DoorBird admin account (ending with 0000) or a viewer account.
The redirect_uri is the url, which will be called after the authentication finished. For a successful authentication the example above will redirect to
https://redirecturl.com/handleOauthResponse.php?state=mystate&code=7f4688a3925b06e44ce1fb45f0d22c
The parameter state can be freely used to handle internal states in the application.
The parameter code which will be received by the redirect url is used for the next step to request an access and refresh token.
The request for getting the access and refresh token has to be a POST request including the needed parameters as application/x-www-form-urlencoded data which should be sent by a server.
curl -X POST -d "grant_type=authorization_code&client_id=9fc9e786-2069-4810-b4c0-618ae54de882&client_secret=7598c79cc4370b8e1e84cab937822b7992876688d43a0865040fc02768f7ad1d&code=7f4688a3925b06e44ce1fb45f0d22c&redirect_uri=https://redirecturl.com/handleOauthResponse.php" token
This will result in a response like the following one:
{
"access_token": "cbbfb5c8a4a743d6bf19a27ac51213c",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "deviceViewer",
"refresh_token": "d8947f12d6d6e6f15aa2c7c3ac032f0"
}
The application should save the access_token and the refresh_token. The access token is used for the bearer authentication for each API call and the refresh_token is used to update the access_token if it has expired.
A call to the API for triggering the first relay of the door station can be done as following:
curl -X POST "relay/1" -H "Authorization: Bearer cbbfb5c8a4a743d6bf19a27ac51213c" -H "Content-Type: application/json" -d ""
The updating of the access token with a new valid token should also be done via a server, so the client secret is not exposed:
curl -X POST -d "grant_type=refresh_token&client_id=9fc9e786-2069-4810-b4c0-618ae54de882&client_secret=7598c79cc4370b8e1e84cab937822b7992876688d43a0865040fc02768f7ad1d&refresh_token=d8947f12d6d6e6f15aa2c7c3ac032f0" token
This will result in a response like the following one:
{
"access_token": "14514466fdcf18123f4f1d27163869e",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "deviceViewer",
"refresh_token": "4f517c61e7affd1af1ebcefa3b3ae59"
}
If the user would like to disconnect the third party app from the door station the following call can be executed to invalidate the access token:
curl -X POST -d "client_id=9fc9e786-2069-4810-b4c0-618ae54de882&client_secret=7598c79cc4370b8e1e84cab937822b7992876688d43a0865040fc02768f7ad1d&token=14514466fdcf18123f4f1d27163869e" revoke
Descriptions and examples of all availbale API calls can be found here.