​
What is OAuth 2.0?

OAuth 2.0 is an industry-standard authorization framework that enables secure, delegated access to resources without sharing credentials. It allows applications to obtain limited access to a user’s account on an HTTP service, such as social media or cloud storage, on their behalf. Instead of sharing passwords, OAuth 2.0 issues tokens that grant specific permissions, enhancing security and user convenience.

​
Before you begin

In order to start your integration please contact our support team to get set up. You need to provide the following information:
  • Types of accounts you’d like to allow to connect Ziina wallets to your app: Personal, Business or both
  • Redirect URI (explained below)
  • Scopes you would like to request. See available scopes
You’ll receive a client_id, username and password to use with our API.

​
OAuth 2.0 token retrieval process

The API flow is captured in the following diagram:
1

User initiates authorization from YourApp

2

Navigate user to authentication service

  https://auth.ziina.com/oidc/auth
  ?client_id=test
  &response_type=code
  &redirect_uri=https://example.com/callback
  &scope=read_account+write_payment_intents
  &state=xyz123
  • client_id you should obtain in advance (contact us)
  • redirect_uri – URI where user will be redirected after permissions have been granted. Should be shared with us in advance.
  • response_type=code for the Authorization Code grant. Must be always provided.
  • state an optional parameter to track the state between initiating and completing auth
  • prompt this field is optional, but if offline_access scope is required then this value must be set to consent
  • scope – Permissions you want to request. If you need to request multiple permissions you need to join them with + sign. Available scopes can be found here
3

Ziina asks user to grant access

4

User grants permissions at https://auth.ziina.com

5

User is redirected to your redirect_uri

Following query params added to your redirect_uri
  • iss=https://auth.ziina.com
  • code=${authorizationCode} which you need to use to exchange for access and refresh tokens
  • state=${state} if this field was passed initially
6

Exchange code for access_token

Send
  POST /oidc/token?code=${authorizationCode}&redirect_uri=${redirectUri}&grant_type=authorization_code&scope=read_account+write_payment_intents HTTP/1.1
  Host: auth.ziina.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

  grant_type=authorization_code&code=${authorizationCode}&redirect_uri=${redirectUri}&scope=read_account+write_payment_intents
  • authorizationCode is the code, which you got at previous step. Its lifetime is 1 minute.
  • Use username and password provided by support to add basic authorization header with Base64-encoded ${username}:${password} string prepended with the word Basic
7

Ziina responds with access_token

Example response
  {
    access_token: "123Abcdef....",
    expires_in: 9007199254740991,
    scope: "read_account write_payment_intents",
    token_type: "Bearer"
  }
8

Make API calls with the Bearer authorization header

API reference can be found here

​
Optional: refresh your access_token

Once your access_token token expires you might want to get a new one. In order to do that you need to send the following request: 
POST /oidc/token?grant_type=refresh_token&refresh_token=123Abcdef HTTP/1.1
Host: auth.ziina.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

grant_type=refresh_token&refresh_token=123Abcdef
To create the Basic authorization header, encode the string ${username}:${password} in Base64 and prepend it with the word Basic.
In order to get refresh_token you need to add scope=offline_access when you get access_token

​
Available scopes

  • write_payment_intents. Allows to create payment intents and accept payments on users behalf
  • write_refunds. Allows to create and fetch refunds
  • write_webhooks. Allows to create and delete webhooks
  • write_transfers. Allows to transfer money to Ziina users
  • offline_access. Add this scope if you want to get refresh_token
  • read_account. This scope is required if you want to get user account information
Tokens obtained at Ziina website on business connect page have all available scopes assigned.

​
Need help?

If you have questions, visit our help center or contact us at support@ziina.com.