API Reference

Overview

Authentication

Infra authenticates access to the API via Access Keys. Access keys are tied to a specific organization. Access keys can be created and managed in the Infra Dashboard. Be sure to securely store access keys: they have the same level of permissions as the user who creates them.

Versioning

The current API version is 0.17.0

The Infra API is versioned. Requests to the API must contain a header named Infra-Version. Set this header to the version matching the API docs reference you're using, or the version of the server you're using. Once you set this value you can forget about it until you want to use features from newer API versions. A valid version header looks like this:

Infra-Version: 0.17.0

Pagination

Every list response in the API is paginated (split into pages). If the page number and limit (page size) aren't specified, then the response will contain the first page of 100 records.

Paginated requests

List requests accept additional query parameters:

ParameterTypeDescription
pageintPage number to retrieve
limitintNumber of objects to retrieve per page (up to 1000)

Examples:

  • GET /api/grants?page=2 returns the second page of 100 grants.
  • GET /api/users?page=1&limit=10 returns the first page of 10 users
  • GET /api/users?page=2&limit=10 returns the second page of 10 users

Paginated responses

List responses take the form:

{
  "page": 4,
  "limit": 10,
  "totalPages": 40,
  "totalCount": 395
}

Use the totalPages field to determine the number of pages needed to request to get all records with the given limit.

Dates

Infra uses the RFC 3339 timestamp format for any date fields.

Long polling

A select few list endpoints support long polling. Long polling allows for near-instant updates by responding only when data has changed. To make a long polling request, include the lastUpdateIndex query parameter. Use 1 for the initial request.

GET /api/grants?lastUpdateIndex=1

Long polling responses include an additional header, Last-Update-Index with the last index to be used in subsequent long-polling requests. Include the value of this header in subsequent requests:

GET /api/grants?lastUpdateIndex=102850182

Errors

Errors in Infra's API all follow a consistent format:

{
  "code": 400,
  "message": "Name contains invalid characters",
  "fieldErrors": [
    {
      "name": ["invalid character at position 4"]
    }
  ]
}

Status Codes

Status CodeSummary
200The request worked as expected
201 - CreatedThe requested resource was created
400 - Bad requestInvalid request parameters
401 - UnauthorizedNo access key was provided
403 - UnauthorizedThis user or access key does not have permission to perform the request
404 - Not foundThe requested resource was not found
409 - ConflictThe request conflicts with an existing resource (e.g. a duplicate)
429 - Too many requestsToo many requests have been sent to the API
500 - Server errorThere was an internal error with Infra's API

Access Grants

Access grants are the core resource in Infra that decides access control. They tie together three concepts:

  1. The user or group
  2. The privilege (e.g. a role or permission)
  3. The resource (e.g. a server, cluster or namespace)

List access

GET /api/grants

This endpoint offers a way to list all grants on the system, and optionally filter using any of the query parameters. A request can include no query parameters, one query parameter, or many to help you find the grants that meet any criteria. Also supports long polling using the lastUpdateIndex query parameter. See Long Polling for more information.

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Query Parameters

FieldFormatDescription
userstringID of user granted access
groupstringID of group granted access
resourcestringa resource name
destinationstringname of the destination where a connector is installed
privilegestringa role or permission
showInheritedbooleanif true, this field includes grants that the user inherits through groups
showSystembooleanif true, this shows the connector and other internal grants
lastUpdateIndexintegerset this to the value of the Last-Update-Index response header to block until the list results have changed
pageintegerPage number to retrieve
limitintegerNumber of objects to retrieve per page (up to 1000)

Example Request

curl -X GET https://api.infrahq.com/api/grants?user=6TjWTAgYYu \
    &group=6k3Eqcqu6B \
    &resource=production.namespace \
    &destination=production \
    &privilege=view \
    &showInherited=true \
    &showSystem=false \
    &page=1 \
    &limit=100 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY'

Returns

Returns list of all grants matching the criteria specified in the query parameters

Example response

{
  "count": "100",
  "items": [
    {
      "created": "2022-03-14T09:48:00Z",
      "created_by": "4yJ3n3D8E2",
      "group": "3zMaadcd2U",
      "id": "3w9XyTrkzk",
      "privilege": "admin",
      "resource": "production.namespace",
      "updated": "2022-03-14T09:48:00Z",
      "user": "6hNnjfjVcc"
    }
  ],
  "limit": 100,
  "page": 1,
  "totalCount": 485,
  "totalPages": 5
}

Example response parameters

FieldTypeDescription
items.createdstringformatted as an RFC3339 date-time
items.created_bystringid of the user that created the grant
items.groupstringGroupID for a group being granted access
items.idstringID of grant created
items.privilegestringa role or permission
items.resourcestringa resource name in Infra's Universal Resource Notation
items.updatedstringformatted as an RFC3339 date-time
items.userstringUserID for a user being granted access

Grant access

POST /api/grants

This endpoint will allow you to create a new grant allowing a user or group a specified level of access to any resource.

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Body Parameters

FieldFormatDescription
groupstringID of the group granted access
groupNamestringName of the group granted access
privilegestringa role or permission
resourcestringa resource name in Infra's Universal Resource Notation
userstringID of the user granted access
userNamestringName of the user granted access

Example Request

curl -X POST https://api.infrahq.com/api/grants \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY' \
  -d '{
    "privilege": "view",
    "resource": "production",
    "user": "6kdoMDd6PA",
  }'

Returns

Returns the grant object, with an additional field wasCreated that is true if this grant did not previously exist.

Example response

{
  "created": "2022-03-14T09:48:00Z",
  "created_by": "4yJ3n3D8E2",
  "group": "3zMaadcd2U",
  "id": "3w9XyTrkzk",
  "privilege": "admin",
  "resource": "production.namespace",
  "updated": "2022-03-14T09:48:00Z",
  "user": "6hNnjfjVcc",
  "wasCreated": true
}

Example response parameters

FieldTypeDescription
createdstringformatted as an RFC3339 date-time
created_bystringid of the user that created the grant
groupstringGroupID for a group being granted access
idstringID of grant created
privilegestringa role or permission
resourcestringa resource name in Infra's Universal Resource Notation
updatedstringformatted as an RFC3339 date-time
userstringUserID for a user being granted access
wasCreatedbooleanIndicates that grant was successfully created, false it already existed beforehand

Update access

PATCH /api/grants

Allows for bulk adding and removing grants

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Body Parameters

FieldFormatDescription
grantsToAddarrayList of grant objects. See POST api/grants for more
grantsToRemovearrayList of grant objects. See POST api/grants for more

Example Request

curl -X PATCH https://api.infrahq.com/api/grants \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY' \
  -d '{
    "grantsToAdd": [{
      "userName": "bob@example.com",
      "privilege": "view",
      "resource": "aws-dev"
    },
    {
      "userName": "cindy@example.com",
      "privilege": "admin",
      "resource": "aws-dev"
    }]
  }'

Returns

Returns a response code with no body

Example response

Empty Response

Example response parameters

Empty Response

List a specific access grant

GET /api/grants/{id}

Searches for a specific access grant by ID

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Path Parameters

FieldFormatDescription
idstringID of the grant to retrieve

Example Request

curl -X GET https://api.infrahq.com/api/grants/4yJ3n3D8E2 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY'

Returns

Returns all the details for a grant with the ID specified in the path

Example response

{
  "created": "2022-03-14T09:48:00Z",
  "created_by": "4yJ3n3D8E2",
  "group": "3zMaadcd2U",
  "id": "3w9XyTrkzk",
  "privilege": "admin",
  "resource": "production.namespace",
  "updated": "2022-03-14T09:48:00Z",
  "user": "6hNnjfjVcc"
}

Example response parameters

FieldTypeDescription
createdstringformatted as an RFC3339 date-time
created_bystringid of the user that created the grant
groupstringGroupID for a group being granted access
idstringID of grant created
privilegestringa role or permission
resourcestringa resource name in Infra's Universal Resource Notation
updatedstringformatted as an RFC3339 date-time
userstringUserID for a user being granted access

Remove access

DELETE /api/grants/{id}

Deletes any grant with the specified id

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Path Parameters

FieldFormatDescription
idstringID of the grant to remove

Example Request

curl -X DELETE https://api.infrahq.com/api/grants/4yJ3n3D8E2 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY'

Returns

Returns an empty body with a response code

Example response

Empty Response

Example response parameters

Empty Response

Managing Users

Users represent the humans that would connect to a cluster and are defined by an email address.

List users

GET /api/users

List all the users that match an optional query

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Query Parameters

FieldFormatDescription
namestringName of the user
groupstringGroup the user belongs to
idsarrayList of User IDs
showSystembooleanif true, this shows the connector and other internal users
pageintegerPage number to retrieve
limitintegerNumber of objects to retrieve per page (up to 1000)

Example Request

curl -X GET https://api.infrahq.com/api/users?name=bob@example.com \
    &group=admins \
    &showSystem=false \
    &page=1 \
    &limit=100 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY'

Returns

Returns an array of user objects that match an optional query

Example response

{
  "count": "100",
  "items": [
    {
      "created": "2022-03-14T09:48:00Z",
      "id": "4yJ3n3D8E2",
      "lastSeenAt": "2022-03-14T09:48:00Z",
      "name": "bob@example.com",
      "providerNames": ["okta"],
      "updated": "2022-03-14T09:48:00Z"
    }
  ],
  "limit": 100,
  "page": 1,
  "totalCount": 485,
  "totalPages": 5
}

Example response parameters

FieldTypeDescription
items.createdstringformatted as an RFC3339 date-time
items.idstringUser ID
items.lastSeenAtstringformatted as an RFC3339 date-time
items.namestringName of the user
items.providerNamesarrayList of providers this user belongs to
items.updatedstringformatted as an RFC3339 date-time

Create users

POST /api/users

Create a user with a specified name. The next step after creation will depend on whether the server is hosted with Infra Cloud or self-hosted. If using Infra Cloud, the new user will receive an email inviting them to the server. If self-hosted, this API returns a one-time password which will need to be relayed to the user.

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Body Parameters

FieldFormatDescription
namestringEmail address of the new user

Example Request

curl -X POST https://api.infrahq.com/api/users \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY' \
  -d '{
    "name": "bob@example.com"
  }'

Returns

If using Infra (<yourorg>.infrahq.com), the response will show a UserID. If self-hosted, the response will show the ID and a one-time password.

Example response

{
  "id": "4yJ3n3D8E2",
  "name": "bob@example.com",
  "oneTimePassword": "password"
}

Example response parameters

FieldTypeDescription
idstringUser ID
namestringEmail address of the user
oneTimePasswordstringOne-time password (only returned when self-hosted)

Get a user

GET /api/users/{id}

Get a user with the specified ID

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Path Parameters

FieldFormatDescription
idstringID of the user to retrieve

Example Request

curl -X GET https://api.infrahq.com/api/users/4yJ3n3D8E2 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY'

Returns

Returns a single user object

Example response

{
  "created": "2022-03-14T09:48:00Z",
  "id": "4yJ3n3D8E2",
  "lastSeenAt": "2022-03-14T09:48:00Z",
  "name": "bob@example.com",
  "providerNames": ["okta"],
  "updated": "2022-03-14T09:48:00Z"
}

Example response parameters

FieldTypeDescription
createdstringformatted as an RFC3339 date-time
idstringUser ID
lastSeenAtstringformatted as an RFC3339 date-time
namestringName of the user
providerNamesarrayList of providers this user belongs to
updatedstringformatted as an RFC3339 date-time

Update a user password

PUT /api/users/{id}

Update a user's password. If the access key used to access this API belongs to an Infra Admin, then the old password does not need to be provided. Otherwise the old password is required. The password parameter is the new one-time password for the user.

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Path Parameters

FieldFormatDescription
idstringID of the user to update

Body Parameters

FieldFormatDescription
oldPasswordstringOld password for the user. Only required when the access key used is not owned by an Infra admin
passwordstringNew one-time password for the user

Example Request

curl -X PUT https://api.infrahq.com/api/users/4yJ3n3D8E2 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY' \
  -d '{
    "oldPassword": "oldpassword",
    "password": "newpassword"
  }'

Returns

Returns a single user object

Example response

{
  "created": "2022-03-14T09:48:00Z",
  "id": "4yJ3n3D8E2",
  "lastSeenAt": "2022-03-14T09:48:00Z",
  "name": "bob@example.com",
  "providerNames": ["okta"],
  "updated": "2022-03-14T09:48:00Z"
}

Example response parameters

FieldTypeDescription
createdstringformatted as an RFC3339 date-time
idstringUser ID
lastSeenAtstringformatted as an RFC3339 date-time
namestringName of the user
providerNamesarrayList of providers this user belongs to
updatedstringformatted as an RFC3339 date-time

Delete a user

DELETE /api/users/{id}

Delete the user by User ID

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Path Parameters

FieldFormatDescription
idstringID of the user to remove

Example Request

curl -X DELETE https://api.infrahq.com/api/users/4yJ3n3D8E2 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY'

Returns

Returns an empty object

Example response

Empty Response

Example response parameters

Empty Response

Group Management

Groups are used in Infra to manage collections of users. A group can then be associated with a role and cluster via a grant and all users with the group will gain that role and and corresponding access to the cluster.

List groups

GET /api/groups

List all the groups that match an optional query

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Query Parameters

FieldFormatDescription
namestringName of the group to retrieve
userIDstringUserID of a user who is a member of the group
pageintegerPage number to retrieve
limitintegerNumber of objects to retrieve per page (up to 1000)

Example Request

curl -X GET https://api.infrahq.com/api/groups?name=admins \
    &userID=4yJ3n3D8E2 \
    &page=1 \
    &limit=100 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY'

Returns

Returns an array of objects describing each group that match the query

Example response

{
  "count": "100",
  "items": [
    {
      "created": "2022-03-14T09:48:00Z",
      "id": "4yJ3n3D8E2",
      "name": "admins",
      "totalUsers": 14,
      "updated": "2022-03-14T09:48:00Z"
    }
  ],
  "limit": 100,
  "page": 1,
  "totalCount": 485,
  "totalPages": 5
}

Example response parameters

FieldTypeDescription
items.createdstringformatted as an RFC3339 date-time
items.idstringGroup ID
items.namestringName of the group
items.totalUsersintegerTotal number of users in the group
items.updatedstringformatted as an RFC3339 date-time

Create a group

POST /api/groups

Create a new group with a specified name

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Body Parameters

FieldFormatDescription
namestringName of the group

Example Request

curl -X POST https://api.infrahq.com/api/groups \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY' \
  -d '{
    "name": "development"
  }'

Returns

Returns the name and id of the new group

Example response

{
  "created": "2022-03-14T09:48:00Z",
  "id": "4yJ3n3D8E2",
  "name": "admins",
  "totalUsers": 14,
  "updated": "2022-03-14T09:48:00Z"
}

Example response parameters

FieldTypeDescription
createdstringformatted as an RFC3339 date-time
idstringGroup ID
namestringName of the group
totalUsersintegerTotal number of users in the group
updatedstringformatted as an RFC3339 date-time

Get a group by ID

GET /api/groups/{id}

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Path Parameters

FieldFormatDescription
idstringID of the group to retrieve

Example Request

curl -X GET https://api.infrahq.com/api/groups/4yJ3n3D8E2 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY'

Returns

Example response

{
  "created": "2022-03-14T09:48:00Z",
  "id": "4yJ3n3D8E2",
  "name": "admins",
  "totalUsers": 14,
  "updated": "2022-03-14T09:48:00Z"
}

Example response parameters

FieldTypeDescription
createdstringformatted as an RFC3339 date-time
idstringGroup ID
namestringName of the group
totalUsersintegerTotal number of users in the group
updatedstringformatted as an RFC3339 date-time

Delete a group

DELETE /api/groups/{id}

Delete a group with the specified ID. You can find the ID of the group using either GET api/groups or GET api/groups/{id}.

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Path Parameters

FieldFormatDescription
idstringID of the group to remove

Example Request

curl -X DELETE https://api.infrahq.com/api/groups/4yJ3n3D8E2 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY'

Returns

Returns an empty response

Example response

Empty Response

Example response parameters

Empty Response

Managing Providers

Providers is short for OIDC providers and, when used in Infra, are the authoritative source of information about users and groups.

List providers

GET /api/providers

List all the providers that match an optional query

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested

Query Parameters

FieldFormatDescription
namestringName of the provider
pageintegerPage number to retrieve
limitintegerNumber of objects to retrieve per page (up to 1000)

Example Request

curl -X GET https://api.infrahq.com/api/providers?name=okta \
    &page=1 \
    &limit=100 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0'

Returns

Returns an array of provider objects that match an optional query

Example response

{
  "count": "100",
  "items": [
    {
      "authURL": "https://example.com/oauth2/v1/authorize",
      "clientID": "0oapn0qwiQPiMIyR35d6",
      "created": "2022-03-14T09:48:00Z",
      "id": "4yJ3n3D8E2",
      "kind": "oidc",
      "name": "okta",
      "scopes": "['openid', 'email']",
      "updated": "2022-03-14T09:48:00Z",
      "url": "infrahq.okta.com"
    }
  ],
  "limit": 100,
  "page": 1,
  "totalCount": 485,
  "totalPages": 5
}

Example response parameters

FieldTypeDescription
items.authURLstringAuthorize endpoint for the OIDC provider
items.clientIDstringClient ID for the OIDC provider
items.createdstringformatted as an RFC3339 date-time
items.idstringProvider ID
items.kindstringKind of provider
items.namestringName of the provider
items.scopesarrayScopes set in the OIDC provider configuration
items.updatedstringformatted as an RFC3339 date-time
items.urlstringURL of the Infra Server

Working with Destinations

Destinations are where the connectors are installed to. An example of a destination would be a Kubernetes cluster.

List all the destinations

GET /api/destinations

List all the destinations that match an optional query

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Query Parameters

FieldFormatDescription
namestringName of the destination
kindstringKind of destination. eg. kubernetes or ssh or postgres
unique_idstringUnique ID generated by the connector
pageintegerPage number to retrieve
limitintegerNumber of objects to retrieve per page (up to 1000)

Example Request

curl -X GET https://api.infrahq.com/api/destinations?name=production-cluster \
    &kind=kubernetes \
    &unique_id=94c2c570a20311180ec325fd56 \
    &page=1 \
    &limit=100 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY'

Returns

Returns a paginated list of destinations

Example response

{
  "count": "100",
  "items": [
    {
      "connected": true,
      "connection": {
        url: aa60eexample.us-west-2.elb.amazonaws.com,
        ca: -----BEGIN CERTIFICATE-----
            MIIDNTCCAh2gAwIBAgIRALRetnpcTo9O3V2fAK3ix+c
            -----END CERTIFICATE-----
      },
      "created": "2022-03-14T09:48:00Z",
      "id": "7a1b26b33F",
      "kind": "kubernetes",
      "lastSeen": "2022-03-14T09:48:00Z",
      "name": "production-cluster",
      "resources": ['default', 'kube-system'],
      "roles": ['cluster-admin', 'admin', 'edit', 'view', 'exec', 'logs', 'port-forward'],
      "uniqueID": "94c2c570a20311180ec325fd56",
      "updated": "2022-03-14T09:48:00Z",
      "version": "0.17.0",
    }
  ],
  "limit": 100,
  "page": 1,
  "totalCount": 485,
  "totalPages": 5
}

Example response parameters

FieldTypeDescription
items.connectedbooleanShows if the destination is currently connected
items.connectionobjectObject that includes the URL and CA for the destination
items.createdstringformatted as an RFC3339 date-time
items.idstringID of the destination
items.kindstringKind of destination. eg. kubernetes or ssh or postgres
items.lastSeenstringformatted as an RFC3339 date-time
items.namestringName of the destination
items.resourcesarrayDestination specific. For Kubernetes, it is the list of namespaces
items.rolesarrayDestination specific. For Kubernetes, it is the list of cluster roles available on that cluster
items.uniqueIDstringUnique ID generated by the connector
items.updatedstringformatted as an RFC3339 date-time
items.versionstringApplication version of the connector for this destination

Get a destination

GET /api/destinations/{id}

Gets the destination with the specified IDs

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Path Parameters

FieldFormatDescription
idstringID of the destination to retrieve

Example Request

curl -X GET https://api.infrahq.com/api/destinations/4yJ3n3D8E2 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY'

Returns

Returns an object describing the destination

Example response

{
  "connected": true,
  "connection": {
      url: aa60eexample.us-west-2.elb.amazonaws.com,
      ca: -----BEGIN CERTIFICATE-----
          MIIDNTCCAh2gAwIBAgIRALRetnpcTo9O3V2fAK3ix+c
          -----END CERTIFICATE-----
  },
  "created": "2022-03-14T09:48:00Z",
  "id": "7a1b26b33F",
  "kind": "kubernetes",
  "lastSeen": "2022-03-14T09:48:00Z",
  "name": "production-cluster",
  "resources": ['default', 'kube-system'],
  "roles": ['cluster-admin', 'admin', 'edit', 'view', 'exec', 'logs', 'port-forward'],
  "uniqueID": "94c2c570a20311180ec325fd56",
  "updated": "2022-03-14T09:48:00Z",
  "version": "0.17.0"
}

Example response parameters

| Field | Type | Description | | ---------- | ------------------------- | ----------------------------------------------------------------------------------------------- | --- | ------- | ------ | --------------------------------- | | connected | boolean | Shows if the destination is currently connected | | connection | {url: string, ca: string} | URL and CA for destination | | created | string | formatted as an RFC3339 date-time | | id | string | ID of the destination | | kind | string | Kind of destination. eg. kubernetes or ssh or postgres | | lastSeen | string | formatted as an RFC3339 date-time | | name | string | Name of the destination | | resources | array | Destination specific. For Kubernetes, it is the list of namespaces | | roles | array | Destination specific. For Kubernetes, it is the list of cluster roles available on that cluster | | uniqueID | string | Unique ID generated by the connector | | updated | string | formatted as an RFC3339 date-time | | version | string | Application version of the connector for this destination |

Access Keys

Access Keys are used by automated processes to access Infra resources. To create and delete access keys, you must use the CLI or the dashboard.

List all access keys

GET /api/access-keys

Gets a list of all access keys that meet the optional query

Header Parameters

FieldFormatDescription
Infra-VersionstringVersion of the API being requested
AuthorizationstringBearer followed by your access key

Query Parameters

FieldFormatDescription
userIDstringUserID of the user whose access keys you want to list
namestringName of the user
showExpiredbooleanWhether to show expired access keys. Defaults to false
pageintegerPage number to retrieve
limitintegerNumber of objects to retrieve per page (up to 1000)

Example Request

curl -X GET https://api.infrahq.com/api/access-keys?userID=4yJ3n3D8E2 \
    &name=john@example.com \
    &showExpired=true \
    &page=1 \
    &limit=100 \
  -H 'Content-Type: application/json' \
  -H 'Infra-Version: 0.17.0' \
  -H 'Authorization: Bearer ACCESSKEY'

Returns

Returns an array of access key objects.

Example response

{
  "count": "100",
  "items": [
    {
      "created": "2022-03-14T09:48:00Z",
      "expires": "2022-03-14T09:48:00Z",
      "extensionDeadline": "2022-03-14T09:48:00Z",
      "id": "4yJ3n3D8E2",
      "issuedFor": "4yJ3n3D8E2",
      "issuedForName": "admin@example.com",
      "lastUsed": "2022-03-14T09:48:00Z",
      "name": "cicdkey",
      "providerID": "4yJ3n3D8E2"
    }
  ],
  "limit": 100,
  "page": 1,
  "totalCount": 485,
  "totalPages": 5
}

Example response parameters

FieldTypeDescription
items.createdstringformatted as an RFC3339 date-time
items.expiresstringkey is no longer valid after this time
items.extensionDeadlinestringkey must be used within this duration to remain valid
items.idstringID of the access key
items.issuedForstringID of the user the key was issued to
items.issuedForNamestringName of the user the key was issued to
items.lastUsedstringformatted as an RFC3339 date-time
items.namestringName of the access key
items.providerIDstringID of the provider if the user is managed by an OIDC provider