Sandbox

Step 1 – register as a developer

Send an email to avsandare.support@kivra.com with the following information:

• Name of your company
• Company registration number
• Contact person (email address and telephone number)
• What Kivra service(s) you want access to

Within 1 workday, we will send you everything you need to proceed to step 2.

Step 2 – set up sandbox

Your journey in Kivra starts in the sandbox. These are the steps you need to take.

Step 2.1 – get API credentials and supplementary information from Kivra

If you’ve completed step 1 above, you will receive an email with a link the following:

API credentials:

• Client ID
• Client secret

Note! Store your API credentials safely. Don’t share your API credentials in plain text, in mail or other messaging systems.

Supplementary information:

• Tenant key
• A fictional SSN
• Activation code

Step 2.2 – API authentication

Kivra API requests the sender to authenticate. Kivra implements authentication using Oauth2 with Client Credentials flow. Here’s how you authenticate:

Create the RFC 2045 base64 encoding to be used for tenant registration. Replace client_id and client_secret with real values and make sure there are no trailing newlines (echo -n) and that the string is encoded literally (use single quotes and no escaping)

$ echo -n 'client_id:client_secret' | base64

You will receive a string of letters and numbers (e.g. Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=). Use this string along with your API credentials like this:

curl -i -X POST https://sender.sandbox-api.kivra.com/v1/auth \
 -d "grant_type=client_credentials" \
 -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="

The API will respond with an access token, which is valid for 8 hours. The access token will be used in all subsequent API requests requiring authentication. You can request new access tokens at any time.

Step 2.3 – register

Go to https://sandbox-accounts.kivra.com/register and register, using the fictional SSN and activation code we gave you in step 2.1. You will also need to provide an email address and a phone number for 2 step verification.

Step 3 – start developing in sandbox

You’re now ready to start developing your content in the Kivra sandbox.

Step 3.1 – matching recipients

You should always check whether a user can receive content from a tenant by matching your list of recipients against the available recipients in Kivra (see API reference / Match users). However, this doesn’t apply for content that is to be retained.

Step 3.2 – send content

Sending of content is done via the content resource. The metadata in the content resource identifies the user and also determines how the recipient can interact with the content.

For documentation on sending content, see:

• Invoices
• Multiple payment options
• Variable amount
• Letters
• Salary slips
• Bookings

Step 3.3 – error handling

In case of errors, Kivra will report back to let you know what went wrong and what to do about it. This is an important step so don’t skip it. For example, if your content can’t be delivered due to errors, it will be lost. As a result, a recipient might not receive an invoice, which can have severe consequences.

For instructions on error handling, visit API reference / Errors.

Step 3.4 – log in to sandbox and review your content

Your content is now available in the sandbox environment. Review it, iterate and repeat as you see fit. When you’re satisfied with the content, you can move on to the production environment.