New to Kivra sandbox? No problem. Follow these steps to set up your sandbox account, and create content in sandbox.
Setting up the sandbox
Step 1 – register as a developer
Send an email to firstname.lastname@example.org 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:
- 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.
- 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:
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.