Authentication

Zubie customers accessing data for their own account can request an API key.

Partners and 3rd party software providers looking to integrate with Zubie are required to use the OAuth2 flow.

OAuth2

What is OAuth2?

• OAuth2 is an authorization protocol that allows a third-party website or application to access a user's data without the user needing to share login credentials.

• Zubie uses OAuth2 to allow users to quickly grant permission for a third-party to access their Zubie account data, without ever needing to share their password.

• OAuth2 is the industry standard authorization protocol used by companies such as Google, Facebook, and Spotify to manage authentication and grant access to user Data.

The OAuth2 Authorization Code Flow

OAuth2 uses different “flows” depending on what type of application the API is designed to serve. Zubie's API uses the Authorization Code Flow, which is the most common OAuth2 flow type.

There are three entities/roles in the authorization code flow:

• Third-party application (you) - This article is written for application developers (you) who are looking to integrate their application with a user's Zubie data.

• User - This is the user that both you (the third-party application owner) and Zubie have in common. The user is required to be involved in the OAuth2 authorization flow to grant the third-party application permission to access their Zubie account data.

• Zubie - Zubie's API servers, which will verify that the user has granted access and send data to the third-party application.

Step 1: Authorization URL

The first step to the authorization code flow is to generate the authorization URL. This is the URL that the user will be redirected to by the third-party application. The user will then grant or deny access for the third-party application to access their Zubie account data.

The authorization URL uses the following format:

https://login.zubiecar.com/authorize?response_type=code&redirect_uri=CALLBACK_URL&client_id=CLIENT_ID

You will need to replace CALLBACK_URL with the callback url you entered when you registered your Zinc app, and CLIENT_ID with the client ID that was generated after registering your app. You can find these while logged into your Zinc account at https://developer.zubie.com/manage-apps

Step 2: User Grants Access

You will now need to redirect the user to your authorization URL. The user will then be prompted to login to their Zubie account and grant access to your application.

Step 3: Authorization Code

If the user allows access to the application during step 2, an Authorization Code will be returned to your application. The Authorization Code will be returned by redirecting to the callback URL you specified when you registered your application. The URL will resemble something like this if testing on your local machine:

https://localhost.com/callback?code=AUTHORIZATION_CODE

Step 4: Request Access Token

Your application will now use the Authorization Code returned in step 3 to request an access token from Zubie. The Access Token Request will require the AUTHORIZATION_CODE returned in the previous step, along with your CLIENT_ID, CLIENT_SECRET and REDIRECT_URI. You will also need to specify that grant_type=authorization_code.

POST

https://login.zubiecar.com/oauth/token

Request Headers

Header	Value
Content-Type	application/x-www-form-urlencoded

Parameters

Property	Type	Description
grant_type	string	To request an access token, this must be set to authorization_code.
authorization_code	string	The code returned in step 3.
client_id	string	The client_id associated with your Zinc app.
client_secret	string	The client_secret associated with your Zinc app.

IMPORTANT The POST request variables must be sent as 'application/x-www-form-urlencoded' parameters.

Step 5: Receive Auth Tokens

If the Zubie API accepts the authorization code and the access token request is valid, it will issue a response containing an Access Token, Refresh Token, expiration time, and token type. Here is an example response:

{
	"access_token": "rDhvN2ryRqpaJJ0CYVEDBhlcujfYzaUvgtbjanKTHduLB0fN61AtoulsSpuL5Opql0N95LzVtOrjnj0XuzKsOwQDwyIDDeT4mpYPJIjWlLKLhHcM8fPccDprb2432KF43KF3klH9Y2sBLlDNmEIUNXG3DkTPsDRJPsCmRpb1f4GKklDQ1qbXqEryLwZPZm5otAbZA4wyaTlKJvCHDC78DShXUCvqSHVaS5PdCatbZN0ikCZZY4POCa50G",
	"refresh_token": "9SPdefmX39gu8icNOlc9A6oAftO2OpBcdx1AC0EQCzzG9906ERcDDwdxiO2$3d3208tzXwgyMRhYumhQc7HhQNcvP97nN46maySdMIlrytXsJqiljrt9IgAL1c2TSNHDTvFDsfdsiPxJ4136U039tlaaJI3ei0u4v8NyGYNG8CBX29QVcP5a5ZOpHK6ruI7DZhxSRlPXhJEAFZYiEH5lL9SyN9VrJZKCw0IwnZLm46fcmzaJ47Frmv8XBMP3aIviaesDTu",
	"expires_in": 86400,
	"token_type": "Bearer"
}

Step 6: Refresh Access Token

When the Access Token expires, you can use the Refresh Token to request a new Access Token.

POST

https://login.zubiecar.com/oauth/token

Request Headers

Header	Value
Content-Type	application/x-www-form-urlencoded

Parameters

Property	Type	Description
grant_type	string	To refresh an access_token, this must be set to refresh_token.
refresh_token	string	The refresh_token returned in step 5.
client_id	string	The client_id associated with your Zinc app.
client_secret	string	The client_secret associated with your Zinc app.

IMPORTANT The POST request variables must be sent as 'application/x-www-form-urlencoded' parameters.

Step 7: Make API Calls

Congratulations! If you’ve received an access token and refresh token, you’ve completed the OAuth2 integration process and can now make API calls to the Zubie user’s account using the Access Token.

To make an API call using the access token, include the access token in the header of the request with the following format:

Authorization: Bearer {OAUTH TOKEN}

Example:

‘Authorization’ : ‘Bearer rDhvN2ryRqpaJJ0CYVEDBhlcujfYzaUvgtbjanKTHduLB0fN61AtoulsSpuL5Opql0N95LzVtOrjnj0XuzKsOwQDwyIDDeTfds4FPJIjWlLKLhHcM8fPccDprb2432KF43KF3klH9Y2sBLlDNmEIUNXG3DkTPsDRJPsCmRpb1f4GKklDQ1qbXqEryLwZPZm5otAbZA4wyaTlKJvCHDC78DSFDD73CvqSHVaS5PdCatbFD50ikCZZY4POCa50G’

For more information on making API requests, please see the Zubie API Reference.

API Key

Individual account owners can request an API key for direct access to their account. Please email support@zubie.com to request an API key. Note that an API key is like a permanent password to your account. Always use caution when sharing and storing your API key.

To use an API key to access the API, include the API key as a request header:

Zubie-Api-Key: {api key}

Additional Resources

For further reading on the OAuth2 standard and implementation, oauth.com and Digital Ocean provide great resources.