Authorization

Authorization is provided via OAuth 2.0. Fakturoid supports Authorization Code Flow and Client Credentials Flow.

Authorization Code Flow should be used for multi-tenant applications (e.g. Shopify) where you need to provide access for multiple users to their accounts.

Client Credentials Flow can be used for the cases of creating either scripts without server component or if you want your own service to access just your Fakturoid account. Using Client Credential Flow for multi-tenant applications is not recommended and can lead to removal of access to your integration.

For development purposes, we recommend configuring your hosts file to point any custom domain to your localhost. You can then use this custom domain at your "URL for redirect". This method serves as one of the possible workarounds of usual development needs, as we do not permit the direct use of localhost as the "URL for redirect" for security reasons.

Authorization Code Flow

Before you can use Authorization Code Flow you need to create an integration in Fakturoid. If you don't already have an account, create a new one. In your account, go to Settings → Connect other apps → OAuth 2 for app developers and create a new integration.

After creating the integration you will receive Client ID and Client Secret which you will need to use in the communication with API.

We recommend you to create at least two integrations once for testing and second for production. This way you can test your integration without affecting your production data.

You can find complete description of Authorization Code Flow in RFC 6749.

Obtaining an authorization code

Redirect the user from your application to the following URL with query parameters:

URL

Query Parameters

If user is already logged into Fakturoid a confirmation page will be shown where he can allow the integration access the his account. Logged-out user will be presented with a log-in form with an option to create an account if he doesn't have one.

After the user allows the access Fakturoid will redirect the user to the Redirect URL specified in the integration settings with authorization code passed via query parameters (see below).

Query Parameters

Obtain Access and Refresh Token

Make sure to call this endpoint within 5 minutes after obtaining the authorization code. Failure to do so will require the user to allow integration access again.

{
  "grant_type": "authorization_code",
  "code": "1d4e…981d",
  "redirect_uri": "https://www.example.org/redirect"
}

{
  "access_token": "26e53aa3244b4c0aed56cb54a0223484e9c4aea49b09a03e4600ba995811b6af06428afc223c4c0c",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "55cfe5cc5e38e8da9646395958d4d681dd9385597f1c346aa6495ebd5b922024cd180b9b61077861"
}

Refresh Access Token

Access token expires after 2 hours and will need to be refreshed. Refreshing doesn't require the user to allow integration access again.

{
  "grant_type": "refresh_token",
  "refresh_token": "55cf…7861"
}

{
  "access_token": "63cfcf07492268ab0e3c58e9fa48096dc5bf0a9b7bbd2f6f45e0a6fa9fc2074a4523af3538f0df5c",
  "token_type": "Bearer",
  "expires_in": 7200
}

Revoke access

Revoking deletes both access and refresh tokens (the user will need to allow integration access again if needed).

{
  "token": "55cf…7861"
}

Client Credentials Flow

Before you start, go to your Fakturoid account and download your Client ID and Client Secret from your user screen Settings → User account. You can generate multiple credentials in your account and use them for authorization.

You can find a complete description of Client Credentials Flow in RFC 6749.

Obtain Access Token

Access token expires after 2 hours after which needs to be obtained again (there is no refresh endpoint).

{
  "grant_type": "client_credentials"
}

{
  "access_token": "26e53aa3244b4c0aed56cb54a0223484e9c4aea49b09a03e4600ba995811b6af06428afc223c4c0c",
  "token_type": "Bearer",
  "expires_in": 7200
}

How to use access token

All requests to Fakturoid API must include the access token in the Authorization header in the following format:

Authorization: token_type access_token

For example when you receive the access token from the token endpoint:

{
  "access_token": "26e53aa3244b4c0aed56cb54a0223484e9c4aea49b09a03e4600ba995811b6af06428afc223c4c0c",
  "token_type": "Bearer",
  "expires_in": 7200
}

You will use it in the Authorization header like this:

Authorization: Bearer 26e53aa3244b4c0aed56cb54a0223484e9c4aea49b09a03e4600ba995811b6af06428afc223c4c0c