# Access Keys

Access keys are credentials used to authenticate as an integration installation, which is scoped to a tenant's site. They provide an easy way to access a site's data without requiring user:password authentication, and the use of tokens.

It is the only way to access Core, Gestal and Herd Management resources.

Integrator Account

Access keys manipulations are only available through your integrator account.

Treat access keys with care

Like a password, an access key will never expire. Please obfuscate or hide it from unwanted eyes.

Access keys are created by specifying an installation ID. You can virtually create as many access keys as you want, however too many access keys emitted will increase the security risk. We recommend removing unused keys as soon as possible, the last_active_at attribute can be useful to determine that.

# Endpoints

# All access keys

https://api.gestal.cloud/integrator/access-keys

# Specific access key

https://api.gestal.cloud/integrator/access-keys/:access_key_id

# Access keys of specific installation

https://api.gestal.cloud/integrator/installations/:installation_id/access-keys

# The access key object

Attribute	Type	Description
`access_key`	string	The access key credential (can be obfuscated, starts with `ak_`).
`last_active_at`	string	Last time this access key was used (null if never used).

# Example Response

Upon successful creation, the access key is returned.

{
  "access_key": "ak_12345678901234567890124567890",
  "last_active_at": null,
  "created_at": "2001-01-01T01:01:01.000Z"
}

Please note

The access_key attribute will only be revealed at creation and will obfuscated afterwards. Like so:

{
  "access_key": "ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxx7890",
  "last_active_at": null,
  "created_at": "2001-01-01T01:01:01.000Z"
}

Obfuscated

Access keys credentials are obfuscated for security reasons. The last four characters are revealed to help you identify the access key you want to deal with.

With the endpoint to obtain all your access keys.

{
  "owner": {
    "integration_name": "My integration",
    "tenant_name": "Tenant 1",
    "site_name": "Site 1"
  },
  "access_key": "ak_xxxxxxxxxxxxxxxxxxxxxxxxxxxx7890",
  "last_active_at": null,
  "created_at": "2001-01-01T01:01:01.000Z"
}

# Authenticate as installation

Authentication as integration installation requires an access key.

# Example Request

GET https://api.gestal.cloud/integration 'Authorization: Basic <access_key>'

No tokens

Unlike your integrator account, there is no session tokens for installations. You must authenticate with basic auth for every request.

Treat access keys with care

Access keys grants you access to complete tenant's site data. Please obfuscate or hide them from unwanted eyes.

# Example Response

{
  "cloud_id": "inst_JbB8eEQnk4qy5vp2LN6BzTjpIAR4BJwD",
  "name": "My integration",
  "url": "https://google.com",
  "type": "third_party",
  "description": "Integrate Vision Web API with My integration notification service.",
  "access_key": {
    "last_active_at": "2001-01-01T01:01:01.000Z"
  },
  "tenant": {
    "cloud_id": "te_8a2o8SNgPSwRmJIUClddClR6Ecwj0Kvl",
    "name": "Tenant 1"
  },
  "site": {
    "cloud_id": "sit_VbRdHhAiizrPScy3TjNH28Ijfvqd6xGc",
    "name": "Site 1"
  }
}

← Installations Introduction →