Integration agreement

Security

When you are given access to our services, you are assigned a set of credentials. These credentials must be kept safe at all times, and must not be transferred or stored in an unsafe way.

• Certificate credentials: In most cases we will ask you to generate a private/public-key, and send us the public key (which is not secret). You must ensure that the private key never leaves a secure context, and never send it to anyone, including us.
  • If the private key is lost, or compromised, generate a new private key and send us the new public key as soon as possible. We will lock access using the old credentials.
  • It is your responsibility to renew credentials before they expire, and give us at least two weeks to update the public key. Make sure you have a system to get notifications in due time.
  • Credentials should never last more than 2 years. This makes sure renewals is part of the normal working process, and that any lost credentials are eventually removed.
• Token credentials: Tokens are issued once certificate credentials are presented to our token service.
  • Tokens expire very fast, usually within 60 minutes. They must be automatically renewed using certificate credentials before they expire.
  • You must cache tokens for at least 70% of the token lifetime (At least 42 minutes for a 60 minute expiry). You are not allowed to request a new token for every request to our APIs.
  • Any temporary connection strings or other secrets must also be kept as long as possible.

Checklist:

• I promise to keep secrets safe
• I promise to renew secrets (tokens/certificates) when needed
• I promise to keep secrets (like tokens) for as long as possible

Deprecation

Our services are in general backwards compatible, but sometimes functionality is changed or removed. Once you are notified that functionality is deprecated, you have minimum 6 months to change your implementation (at your own cost) to use a newer version. If this is not done, your implementation might stop working. You must handle any extension to our services (like new endpoints, types, fields and attributes). Note: When we implement changes in our APIs that are not backwards compatible, we release this as a new version of the API. The old and new version will work in parallel. In practice, any 3rd party will most likely have at least 12 months to plan and implement support for a new version.

Checklist:

• I promise to update my implementation when functionality is deprecated
• I promise to automatically handle any service extensions

Release cadence

Updates to the API’s are released continuously, without specific notification to 3rd parties​, but with no downtime.

Checklist:

• I accept that updates are continuously released

Error handling

We cannot guarantee 100% uptime, so you should expect and handle errors at any time. This includes errors in the network between you and us, internally in our services or services we depend on. Most errors are transient, so the operation should be retried at least 3 times with an appropriate back-off policy (retry after 10 seconds, then 30, then 60 etc.). We do not consider it an error until you have retried at least 2 times. Some operations are idempotent, and thus can be retried without any side effect. This means that if you are unsure if your request was received and handled (you did not get a response), please retry your request.

Checklist:

• I promise to handle errors, and retry if appropriate

Traffic volume

Before you start using our services, you must let us know the expected:

• Average number of requests (per hour / day / month)
• Average size of requests (in kB)
• Any expected spikes in usage (weekly campaigns, Black Friday, Christmas etc.)

Checklist:

• I promise to estimate my expected volume

Incorrect usage

It is important that you use our services in the expected and agreed way, this will ensure we can deliver the best possible service for all our customers/users.

• Do not send traffic to endpoints that do not exist, or to retrieve data you know does not exist
• Do not send unneeded traffic, for example when results can be cached
• Do not enumerate over all the data in the service to store it locally, unless this is explicitly agreed.
• Most services are simple request/response for single entities, if you want to synchronize all changes to data, we have separate endpoints for that.

Checklist:

• I promise to use the service correctly