GOpenCSR API terms

What these terms cover

These terms apply to the API front door of the G Open services and to every API key. You accept them when you create an API key, and the account records the version you accepted. They add to the GOpenCSR terms and the acceptable use policy. What you change through the API is governed by the registry it belongs to, under the GOpenCDR terms or the GOpenCNR terms.

The front door

One API reference and one key system serve all three services:

• GOpenCDR: https://csr.gplatform.org/api/cdr/v1
• GOpenCNR: https://csr.gplatform.org/api/cnr/v1
• GOpenCSR: https://csr.gplatform.org/api/csr/v1

The front door is for people and for integrators. An application acting for a person signs that person in with OpenID Connect at csr.gplatform.org, using the authorisation code flow with PKCE, and sends the access token it receives. A script sends an API key. Errors come back as application/problem+json, each with a stable code. The reference, with its changelog, is published with the API.

What does not go through it

The machines that keep the services running, and the public that reads them, talk to each service directly:

• GOpenCNR's agents on members' routers and on hubs, under the network participation agreement and the hub operator agreement;
• GOpenCDR's mirrors, under the mirror operator terms;
• public fetchers, such as RDAP clients, relying parties that fetch GOpenCNR's RPKI repository under the TAL and repository terms, and anybody reading the transparency log at csr.gplatform.org/tlog.

These terms do not apply to them.

API keys

• Made in the account and shown once. You create a key under Account, API keys, and its secret is shown when it is created and never again. We keep only its public prefix and a keyed hash of its secret, so a lost key is replaced, not recovered.
• For one product and one environment. The prefix says which: gok_cdr_live_, gok_cdr_test_, gok_cnr_live_ or gok_cnr_test_.
• Scoped. A key carries one or more scopes, each an object type and an action, such as reading routes or changing them, and a scope may be limited to particular objects. A key can do no more than its scopes allow, and no more than your own roles allow.
• Always expiring. A key expires after the time you choose, which is at most 400 days. If you choose none, it expires after 90 days. Create the next key before the old one runs out.
• Never Tier 0. No key carries Tier 0 permissions, and no key can decide an approval or manage keys.
• Optionally tied to addresses. You may give a key an allowlist of addresses, and requests with it from anywhere else are refused.
• Its last use is recorded and shown with the key.
• Wrong keys are counted. Failed key attempts are limited to 30 from one address in 15 minutes; beyond that, attempts from that address are refused.

Changes that need a signature

A key does not sign. A request for a change that needs the holder's signature is answered with 202 Accepted and a signing link, and the change applies only once it is signed: by a person with a passkey in the signing step on csr.gplatform.org, or by an automation key registered under a passkey. The receipt is the change's entry in the transparency log.

Rate limits

Each key may make 600 requests a minute. Responses carry RateLimit-* headers that say where you stand. A request over the limit is refused with status 429 Too Many Requests, and the response says when to retry. Do not get around the limit by spreading requests over several keys, accounts or addresses.

Idempotency and pagination

• Idempotency. Send an Idempotency-Key header with every POST. A request repeated with the same key within 24 hours returns the answer to the first one instead of acting twice. The records are kept for 24 hours.
• Pagination. Lists are read by cursor, with ?after=<cursor>&limit=<n>. A page holds 100 items unless you ask for another number, and at most 500.

Keeping keys safe

You are responsible for your keys and for what is done with them: a request made with a key is made in your account's name, for the holder its scopes cover. Keep keys out of source code, public repositories, code that runs in a browser, URLs and logs. Give each key the narrowest scopes, an address allowlist where you can, and the shortest life that works. If a key may be exposed, revoke it at once, and tell us at contact@gplatform.org if it may have been misused.

Revocation

You may revoke a key at any time, and from then on it is refused. We revoke a key that is exposed or misused, that is used against these terms or the acceptable use policy, or whose account is suspended or closed. You are told why, with a statement of reasons, and may challenge it, as the GOpenCSR terms describe for every restriction.

Versions and changes

The version is part of every path, as in /v1. Within a version, the API grows without breaking what exists: new endpoints, new fields and new error codes may appear, and a client ignores what it does not know. A change that would break a working client comes as a new version. The changelog records every change.

A version is withdrawn only after notice in advance to the address of every account whose keys use it, and the notice names the date and the version that replaces it.

These terms change only as the general terms set out under "New versions of these terms": a material change is emailed to your address at least six weeks before it takes effect, and at your next sign-in you are asked to accept the new version, which is shown to you in full and linked in the document archive, without a list of what changed. A new version applies to you only once you accept it. What applies if you have not accepted it when the six weeks are over is set out in the GOpenCSR terms, under "Your content, your account and these clauses". Every version of these terms stays in the document archive.

Acceptable use

The acceptable use policy applies to every request. In particular: no harvesting, no load-testing or probing beyond what the security and disclosure policy allows, and no scripting of the sign-in pages or the consoles in place of the API.

What is recorded

Every request is written to a request log, which is deleted after 14 days. Every change made with a key writes an audit record that names the key as the actor. The privacy notice says what else is kept, and for how long.

Everything else

The API is provided free of charge. Warranty, service levels and the limits of our liability are as set out in the general terms of service; for what is given away, liability is limited to intent and gross negligence (Section 521 BGB).