Authorization
The DoorFlow API allows two methods of authorization:
- OAuth 2.0 standard as documented here: https://tools.ietf.org/html/rfc6749.
- Personal API keys which are a simple authorization method useful for headless scripts and other applications where OAuth is not suitable.
OAuth 2.0
Currently, we only support the Authorization Code Grant for the public DoorFlow API.
Some additional notes on the security of tokens here
Your Developer account
Before starting, create a DoorFlow application. To do this follow the steps below:
Step 1. Register as a developer
If you have not done this yet, register a developer account here.
Your developer account credentials are independent of your DoorFlow account so your existing DoorFlow account credentials will not work here.
Step 2. Create an application
Once you sign in you will be redirected to the list of your Applications. Now you are ready to create your first OAuth app.
An application is created with a client_id and client_secret which are used to identify your applications and are required to complete the authorization process.
The list below highlights the OAuth 2.0 scopes that you might need to request to access DoorFlow APIs, depending on the level of access you need. Sensitive scopes require review by DoorFlow. Note that some scopes overlap.
| Scope | User Facing Description |
|---|---|
| account.person.readonly | View person related information |
| account.person | View and manage customer related information |
| account.role.readonly | View role related information |
| account.shift.readonly | View shift related information |
| account.channel.readonly | View channel related information |
| account.event.readonly | View event related information |
| account.site.readonly | View site related information |
| account.reports.readonly | View report related information |
redirect_uri is the address of your server which will accept the callback request from DoorFlow.
OAuth App States
Once created your new app can be in an Inactive state.
The definition of these three states are shown below.
| State | Notes |
|---|---|
| Inactive | We’ve been notified of your new app and we’ll create a DoorFlow test account for you to test against. We’ll email you once this is ready with further details. Once the test account is setup you’ll be able to use it to test your integration against. Next step: We’ll create a DoorFlow test account and link it to your application. |
| Testing | Your application is linked to a DoorFlow test account and can now be used for testing. The DoorFlow test account can have several virtual channels/doors attached which generate access events from time to time so that you get a good feel for how things work. We can disable automatic event generation if needed - just let us know |
| Live | Congratulations! Your application is live and can be used by customers. You should not make significant changes to your integration once it’s been published. You can create as many applications as you like - and if you need a new [test] account setup, please let us know. |
OAuth App Approval
In the Testing state your app can only be used with a single DoorFlow account. In order to use your app with any DoorFlow account, we need to approve your integration. Once approved your app will show as Live.
To do this we suggest a short call or screen recording to demonstrate how your app links to DoorFlow. Specifically we'll be looking for clean user flow, correct terminology and accurate branding materials.
Once approved we'd like to publish your application in our App Directory. We'll likely need a few more details to do this, but we'll be in touch.
You only need to get our approval for production ready, public applications.
You can have as many OAuth apps as you like. We'd advise that you keep the usual standard environments; testing, staging and production. You might choose to have several versions of you production app over time. We'd advise against making changes to a live app.
Connecting your application
Implement the following steps to connect your application to a DoorFlow account:
Step 1. Requesting authorization code
The DoorFlow account admin (resource owner) needs to authorize your application to access their [DoorFlow] data.
In your application have a button or link that sends them to the following URL so that they can authorize your application.
https://admin.doorflow.com/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scopes}&state={state}
In OAuth 2.0, the developer (who is building the client application) does not need to specify the user account they are trying to access during the authorization request. The OAuth flow relies on the end-user (e.g., the DoorFlow account holder) to grant access. When the user logs in and authorizes the app, the token issued will be tied to that user’s account.
| Parameters | Meaning |
|---|---|
| client_id | As defined in your developer app listing |
| redirect_uri | As defined in your developer app listing |
| scopes | Your approved scopes (space separated) |
| state | An opaque value used by the client to maintain state between the request and callback. DoorFlow includes this value when redirecting the user-agent back to the client redirect_uri. If you wish to associate a DoorFlow token with a resource on a client then you can pass this client resource ID in using the state parameter and it will be returned in the redirect_uri. (optional) |
The redirect_uri must be exactly the same as what is registered for the app in your developer dashboard.
Once the DoorFlow account user has authorized the application, DoorFlow will send an authorization code to the redirect URI you set up with your OAuth application.
A successful authorization response:
{redirect_uri}?code={code}
A declined access response:
{redirect_uri}?error=access_denied
The redirect_uri should be defined exactly as it was when creating your application, without any additional parameters.
Step 2. Requesting an access token
Once you have the authorization code, your application can now request an access token and a refresh token.
The following data should be sent as application/x-www-form-urlencoded encoded body of a POST request.
NOTE: This data should not be sent as GET parameters in a query string.
| Parameters | Notes |
|---|---|
| client_id | As defined in your developer app listing |
| client_secret | As defined in your developer app listing |
| redirect_uri | As defined in your developer app listing |
| grant_type | Either authorization_code or refresh_token |
| code | Use the code returned from step 1 above |
| refresh_token | Only used for the refresh_token grant type |
The authorization code is a short-lived (10 minutes), single-use value. Based on that assumption, every new authorization request should start with Step 1.
Response
{
"access_token": "fMYgxHEYtcyT8cvtvgi1Za5DRs4vArSyvydlnd9f",
"token_type": "Bearer",
"refresh_token": "J55mRvxaWjMShlrm3OhT4-Us6WTXjykvB_cRJUDM52U",
"scope": "account.person account.role.readonly account.shift.readonly",
"expires_in": 3600
}
The expires_in value is a relative time duration in seconds since this response was created. Currently, access tokens expire after 1 hour and can refreshed using the refresh_token grant flow.
Step 3. Which account does a token belong to?
Once you have been issued a token you can find out information about that token, such as which account it relates to along with information about it's scopes and expiration.
If your application is used by multiple DoorFlow accounts you can easily find out which account the token belongs to here.
Authorization: Bearer fMYgxHEYt8cvtvgi1Za5DRs4vArSyvydlnd9f
Response
{
"resource_owner_id": 1995,
"account_id": "7YxfBm",
"scope": [
"account.channel.readonly",
"account.event.readonly",
"account.site.readonly"
],
"expires_in": 3518,
"application": {
"uid": "LxSYePecl4vQoeeRTxP1mAX4uw-22mGOd2XvGMyVdJ8"
},
"created_at": 1729243997
}
Step 4. Using the token to access the DoorFlow API
Your application can now use the received access token to interact with the DoorFlow API on behalf of the customer by providing the access token in an Authorization header.
Authorization: Bearer fMYgxHEYt8cvtvgi1Za5DRs4vArSyvydlnd9f
Some additional notes on the security of tokens here
For when you can't use OAuth
Shell
$ curl -H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u APIKEY0123456789:xxx \
-d '{"request": {"name":"some value"}}' https://api.doorflow.com/
The DoorFlow API also supports the use of API keys for those use cases where the OAuth flow isn't necessary or wouldn't work. Good examples of those are scripts running periodically in the background or desktop applications.
API keys use HTTP Basic Authentication and need to be enabled on a per User basis.
Every request must include the Authorization HTTP header, or it will be rejected by the API servers.
Use your API token as the username. For the password, use X or some otherwise bogus text.
Your API token is available from your DoorFlow Account Settings screen, under API keys.
All calls to your DoorFlow account must be made over SSL. If you have any security concerns or questions just drop us an email to support@doorflow.com.