Account, keys and webhooks ›

Set api key allow from

PUT/v1/api-keys/{id}/allow-from

Replaces the addresses the key may be used from, from its next request. It is the only thing about a key that changes after it is made. An empty list is anywhere. A key used to change one, itself included, may set only addresses inside its own. While the account has two-factor sign-in on, a person signed in sends a code with a list that lets the key be used from more places.

RequestTypeScript

import { Agental } from "agental-sdk";
const agental = new Agental();
await agental.apiKeys.setAllowFrom("key_9b1c7e2f4a6d8053", ["203.0.113.0/24"]);

Answer200 OK · ApiKey

{
"id": string,
"name": string,
"prefix": string | null,
"createdAt": string,
"seesAll": boolean,
"preset": "read-only" | "full-sandbox" | "ci" | "admin" | "null" | null,
"actions": string[],
"sandboxIds": string[],
"templateIds": string[],
… 6 more
}

The key, with its addresses from now on.

Path

idrequired

string

e.g. "key_38b536dc2eabdb52"

Headers

Authorizationrequired

Bearer key

An API key that may make this call.

Body

allowFromrequired

array of string

IPv4 and IPv6 addresses and ranges the key may be used from, 100 at most: an address alone is that one computer, and a range is written as 203.0.113.0/24 or 2001:db8::/48. An IPv4 address written the IPv6 way, as ::ffff:203.0.113.7, is that IPv4 address. Empty, or left out, is anywhere. A request from any other address is refused with 403 key_address_forbidden. A sandbox reaches the API from its server's shared IPv4 address, which changes when it moves, so limit a key used inside a sandbox with sandboxIds instead. On a network with IPv6 the API sees your IPv6 address, so a list of IPv4 addresses alone refuses you there. e.g. ["203.0.113.0/24","2001:db8::/48"]

code

string

For a person signed in to the site whose account has two-factor sign-in on, and a list that lets the key be used from more places: an address outside the list it had, or anywhere in place of a list. The six digits the authenticator app shows now, or one of the backup codes, which is then used up. A list that only narrows it needs none, and so does a call made with an API key. e.g. "482913"

Returns

200 The key, with its addresses from now on.

ApiKey15 fields

id

string

name

string

prefix

stringnull

The first characters of the secret, to tell keys apart by.

Null for a key from before they were kept.

createdAt

string

seesAll

boolean

True for a key of whoever runs the service, which sees every account.

preset

read-onlyfull-sandboxciadminnullnull

The preset the key was made with.

Null for one made with its actions named.

actions

string[]

What the key may do, as it was made: a preset is written out into its actions then, so a preset that grows later does not widen it.

* is everything.

sandboxIds

string[]

The sandboxes the key is limited to, with templateIds.

Empty, with templateIds empty too, is every sandbox of the account.

templateIds

string[]

The templates the key is limited to: it reaches them and every sandbox on them.

Empty is every template, and, with sandboxIds empty too, every sandbox.

expiresAt

stringnull

When the key stops working.

Null is never.

allowFrom

string[]

The addresses and ranges the key may be used from.

Empty is anywhere.

lastUsedAt

stringnull

When the key was last used, to the minute: it is written once a minute at most.

Null if never.

lastUsedFrom

stringnull

The address it was last used from.

organizationId

stringnull

The organization the key acts in: the one it was made in, for good.

Null for a key of whoever runs the service.

createdBy

stringnull

The account that made it.

In a team, its owners and admins see every key of the team, and a member only those they made.

Errors and other answers

400	`invalid_request` an entry is no address or range, and the message says which, or there are more than 100.
400	`code_required` a person signed in, with two-factor sign-in on, sent no code with a list that lets the key be used from more places.
400	`invalid_code` the code is not right.
400	`code_used` six digits from the app that were used already.
403	`key_exceeds_caller` the key used may be used only from some addresses, and the list is not inside them.
403	`role_required` another member of the team made the key, and only they change it.
404	not_found.
409	`dev_key_permanent` the seeded dev key is not limited.
429	`rate_limited` five wrong codes for the account in a quarter of an hour, on this call or another that asks for one.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← Delete api key Get policy →