Infra API

Manage users, groups, grants, destinations, identity providers, and access keys. Auth is `Authorization: Bearer ` plus a required `Infra-Version` header; pagination is page/limit; errors use a {code,message,fieldErrors} envelope.

OpenAPI Specification

infra-openapi-original.json Raw ↑
{
  "openapi": "3.0.0",
  "components": {
    "schemas": {
      "CreateAccessKeyResponse": {
        "properties": {
          "accessKey": {
            "type": "string"
          },
          "created": {
            "description": "formatted as an RFC3339 date-time",
            "example": "2022-03-14T09:48:00Z",
            "format": "date-time",
            "type": "string"
          },
          "expires": {
            "description": "after this deadline the key is no longer valid",
            "example": "2022-03-14T09:48:00Z",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "example": "4yJ3n3D8E2",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          },
          "inactivityTimeout": {
            "description": "the key must be used by this time to remain valid",
            "example": "2022-03-14T09:48:00Z",
            "format": "date-time",
            "type": "string"
          },
          "issuedForID": {
            "example": "4yJ3n3D8E2",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          },
          "issuedForKind": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "providerID": {
            "example": "4yJ3n3D8E2",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          }
        }
      },
      "CreateGrantResponse": {
        "properties": {
          "created": {
            "description": "formatted as an RFC3339 date-time",
            "example": "2022-03-14T09:48:00Z",
            "format": "date-time",
            "type": "string"
          },
          "createdBy": {
            "description": "id of the user that created the grant",
            "example": "4yJ3n3D8E2",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          },
          "group": {
            "description": "GroupID for a group being granted access",
            "example": "3zMaadcd2U",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          },
          "id": {
            "description": "ID of grant created",
            "example": "3w9XyTrkzk",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          },
          "privilege": {
            "description": "a role or permission",
            "example": "admin",
            "type": "string"
          },
          "resource": {
            "description": "a resource name in Infra's Universal Resource Notation",
            "example": "production.namespace",
            "type": "string"
          },
          "updated": {
            "description": "formatted as an RFC3339 date-time",
            "example": "2022-03-14T09:48:00Z",
            "format": "date-time",
            "type": "string"
          },
          "user": {
            "description": "UserID for a user being granted access",
            "example": "6hNnjfjVcc",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          },
          "wasCreated": {
            "description": "Indicates that grant was successfully created, false it already existed beforehand",
            "example": "true",
            "type": "boolean"
          }
        }
      },
      "CreateTokenResponse": {
        "properties": {
          "expires": {
            "description": "formatted as an RFC3339 date-time",
            "example": "2022-03-14T09:48:00Z",
            "format": "date-time",
            "type": "string"
          },
          "token": {
            "type": "string"
          }
        }
      },
      "CreateUserResponse": {
        "properties": {
          "id": {
            "description": "User ID",
            "example": "4yJ3n3D8E2",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          },
          "name": {
            "description": "Email address of the user",
            "example": "bob@example.com",
            "type": "string"
          },
          "oneTimePassword": {
            "description": "One-time password (only returned when self-hosted)",
            "example": "password",
            "type": "string"
          }
        }
      },
      "Destination": {
        "properties": {
          "connected": {
            "description": "Shows if the destination is currently connected",
            "example": "true",
            "type": "boolean"
          },
          "connection": {
            "description": "Object that includes the URL and CA for the destination",
            "properties": {
              "ca": {
                "example": "-----BEGIN CERTIFICATE-----\nMIIDNTCCAh2gAwIBAgIRALRetnpcTo9O3V2fAK3ix+c\n-----END CERTIFICATE-----\n",
                "type": "string"
              },
              "url": {
                "example": "aa60eexample.us-west-2.elb.amazonaws.com",
                "type": "string"
              }
            },
            "required": [
              "ca"
            ],
            "type": "object"
          },
          "created": {
            "description": "Time destination was created",
            "example": "2022-11-10T23:35:22Z",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "ID of the destination",
            "example": "7a1b26b33F",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          },
          "kind": {
            "description": "Kind of destination. eg. kubernetes or ssh or postgres",
            "example": "kubernetes",
            "type": "string"
          },
          "lastSeen": {
            "description": "formatted as an RFC3339 date-time",
            "example": "2022-03-14T09:48:00Z",
            "format": "date-time",
            "type": "string"
          },
          "name": {
            "description": "Name of the destination",
            "example": "production-cluster",
            "type": "string"
          },
          "resources": {
            "description": "Destination specific. For Kubernetes, it is the list of namespaces",
            "example": "['default', 'kube-system']",
            "items": {
              "description": "Destination specific. For Kubernetes, it is the list of namespaces",
              "example": "['default', 'kube-system']",
              "type": "string"
            },
            "type": "array"
          },
          "roles": {
            "description": "Destination specific. For Kubernetes, it is the list of cluster roles available on that cluster",
            "example": "['cluster-admin', 'admin', 'edit', 'view', 'exec', 'logs', 'port-forward']",
            "items": {
              "description": "Destination specific. For Kubernetes, it is the list of cluster roles available on that cluster",
              "example": "['cluster-admin', 'admin', 'edit', 'view', 'exec', 'logs', 'port-forward']",
              "type": "string"
            },
            "type": "array"
          },
          "uniqueID": {
            "description": "Unique ID generated by the connector",
            "example": "94c2c570a20311180ec325fd56",
            "type": "string"
          },
          "updated": {
            "description": "Time destination was updated",
            "example": "2022-12-01T19:48:55Z",
            "format": "date-time",
            "type": "string"
          },
          "version": {
            "description": "Application version of the connector for this destination",
            "type": "string"
          }
        }
      },
      "DeviceFlowResponse": {
        "properties": {
          "deviceCode": {
            "description": "a code that a device will use to exchange for an access key after device login is approved",
            "example": "NGU4QWFiNjQ5YmQwNG3YTdmZMEyNzQ3YzQ1YSA",
            "type": "string"
          },
          "expiresIn": {
            "description": "The number of seconds that this set of values is valid",
            "example": "1800",
            "format": "int16",
            "type": "integer"
          },
          "interval": {
            "description": "the number of seconds the device should wait between polling to see if the user has finished logging in",
            "example": "5",
            "format": "int8",
            "type": "integer"
          },
          "userCode": {
            "description": "This is the text the user will enter at the Verification URI",
            "example": "BDSD-HQMK",
            "type": "string"
          },
          "verificationURI": {
            "description": "This is the URL the user needs to enter into their browser to start logging in",
            "example": "https://infrahq.com/device",
            "type": "string"
          }
        }
      },
      "DeviceFlowStatusResponse": {
        "properties": {
          "deviceCode": {
            "example": "",
            "type": "string"
          },
          "login": {
            "properties": {
              "accessKey": {
                "type": "string"
              },
              "expires": {
                "description": "formatted as an RFC3339 date-time",
                "example": "2022-03-14T09:48:00Z",
                "format": "date-time",
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "organizationName": {
                "type": "string"
              },
              "passwordUpdateRequired": {
                "type": "boolean"
              },
              "userID": {
                "example": "4yJ3n3D8E2",
                "format": "uid",
                "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
                "type": "string"
              }
            },
            "type": "object"
          },
          "status": {
            "description": "can be one of pending, expired, confirmed",
            "type": "string"
          }
        }
      },
      "EmptyResponse": {},
      "Error": {
        "properties": {
          "code": {
            "format": "int32",
            "type": "integer"
          },
          "fieldErrors": {
            "items": {
              "properties": {
                "errors": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "fieldName": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Grant": {
        "properties": {
          "created": {
            "description": "formatted as an RFC3339 date-time",
            "example": "2022-03-14T09:48:00Z",
            "format": "date-time",
            "type": "string"
          },
          "createdBy": {
            "description": "id of the user that created the grant",
            "example": "4yJ3n3D8E2",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          },
          "group": {
            "description": "GroupID for a group being granted access",
            "example": "3zMaadcd2U",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          },
          "id": {
            "description": "ID of grant created",
            "example": "3w9XyTrkzk",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          },
          "privilege": {
            "description": "a role or permission",
            "example": "admin",
            "type": "string"
          },
          "resource": {
            "description": "a resource name in Infra's Universal Resource Notation",
            "example": "production.namespace",
            "type": "string"
          },
          "updated": {
            "description": "formatted as an RFC3339 date-time",
            "example": "2022-03-14T09:48:00Z",
            "format": "date-time",
            "type": "string"
          },
          "user": {
            "description": "UserID for a user being granted access",
            "example": "6hNnjfjVcc",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          }
        }
      },
      "Group": {
        "properties": {
          "created": {
            "description": "Date the group was created",
            "example": "2022-03-14T09:48:00Z",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Group ID",
            "example": "gauEdoYCEU",
            "format": "uid",
            "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
            "type": "string"
          },
          "name": {
            "description": "Name of the group",
            "example": "admins",
            "type": "string"
          },
          "totalUsers": {
            "description": "Total number of users in the group",
            "example": "14",
            "format": "int",
            "type": "integer"
          },
          "updated": {
            "description": "Date the group was updated",
            "example": "2022-03-14T09:48:00Z",
            "format": "date-time",
            "type": "string"
          }
        }
      },
      "ListResponse_AccessKey": {
        "properties": {
          "count": {
            "description": "Total number of items on the current page",
            "example": "100",
            "format": "int",
            "type": "integer"
          },
          "items": {
            "items": {
              "properties": {
                "created": {
                  "description": "formatted as an RFC3339 date-time",
                  "example": "2022-03-14T09:48:00Z",
                  "format": "date-time",
                  "type": "string"
                },
                "expires": {
                  "description": "key is no longer valid after this time",
                  "example": "2022-03-14T09:48:00Z",
                  "format": "date-time",
                  "type": "string"
                },
                "id": {
                  "description": "ID of the access key",
                  "example": "4yJ3n3D8E2",
                  "format": "uid",
                  "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
                  "type": "string"
                },
                "inactivityTimeout": {
                  "description": "key must be used by this time to remain valid",
                  "example": "2022-03-14T09:48:00Z",
                  "format": "date-time",
                  "type": "string"
                },
                "issuedForID": {
                  "description": "ID of the entity the key was issued to",
                  "example": "4yJ3n3D8E2",
                  "format": "uid",
                  "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
                  "type": "string"
                },
                "issuedForKind": {
                  "description": "the kind entity the key was issued for (eg: user, organization, or provider)",
                  "example": "user",
                  "type": "string"
                },
                "issuedForName": {
                  "description": "Name of the user the key was issued to",
                  "example": "admin@example.com",
                  "type": "string"
                },
                "lastUsed": {
                  "description": "formatted as an RFC3339 date-time",
                  "example": "2022-03-14T09:48:00Z",
                  "format": "date-time",
                  "type": "string"
                },
                "name": {
                  "description": "Name of the access key",
                  "example": "cicdkey",
                  "type": "string"
                },
                "providerID": {
                  "description": "ID of the provider if the user is managed by an OIDC provider",
                  "example": "4yJ3n3D8E2",
                  "format": "uid",
                  "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
                  "type": "string"
                },
                "scopes": {
                  "description": "additional access level scopes that control what an access key can do",
                  "items": {
                    "description": "additional access level scopes that control what an access key can do",
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "limit": {
            "description": "Number of objects per page",
            "example": "100",
            "format": "int",
            "type": "integer"
          },
          "page": {
            "description": "Page number retrieved",
            "example": "1",
            "format": "int",
            "type": "integer"
          },
          "totalCount": {
            "description": "Total number of objects",
            "example": "485",
            "format": "int",
            "type": "integer"
          },
          "totalPages": {
            "description": "Total number of pages",
            "example": "5",
            "format": "int",
            "type": "integer"
          }
        }
      },
      "ListResponse_Destination": {
        "properties": {
          "count": {
            "description": "Total number of items on the current page",
            "example": "100",
            "format": "int",
            "type": "integer"
          },
          "items": {
            "items": {
              "properties": {
                "connected": {
                  "description": "Shows if the destination is currently connected",
                  "example": "true",
                  "type": "boolean"
                },
                "connection": {
                  "description": "Object that includes the URL and CA for the destination",
                  "properties": {
                    "ca": {
                      "example": "-----BEGIN CERTIFICATE-----\nMIIDNTCCAh2gAwIBAgIRALRetnpcTo9O3V2fAK3ix+c\n-----END CERTIFICATE-----\n",
                      "type": "string"
                    },
                    "url": {
                      "example": "aa60eexample.us-west-2.elb.amazonaws.com",
                      "type": "string"
                    }
                  },
                  "required": [
                    "ca"
                  ],
                  "type": "object"
                },
                "created": {
                  "description": "Time destination was created",
                  "example": "2022-11-10T23:35:22Z",
                  "format": "date-time",
                  "type": "string"
                },
                "id": {
                  "description": "ID of the destination",
                  "example": "7a1b26b33F",
                  "format": "uid",
                  "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
                  "type": "string"
                },
                "kind": {
                  "description": "Kind of destination. eg. kubernetes or ssh or postgres",
                  "example": "kubernetes",
                  "type": "string"
                },
                "lastSeen": {
                  "description": "formatted as an RFC3339 date-time",
                  "example": "2022-03-14T09:48:00Z",
                  "format": "date-time",
                  "type": "string"
                },
                "name": {
                  "description": "Name of the destination",
                  "example": "production-cluster",
                  "type": "string"
                },
                "resources": {
                  "description": "Destination specific. For Kubernetes, it is the list of namespaces",
                  "example": "['default', 'kube-system']",
                  "items": {
                    "description": "Destination specific. For Kubernetes, it is the list of namespaces",
                    "example": "['default', 'kube-system']",
                    "type": "string"
                  },
                  "type": "array"
                },
                "roles": {
                  "description": "Destination specific. For Kubernetes, it is the list of cluster roles available on that cluster",
                  "example": "['cluster-admin', 'admin', 'edit', 'view', 'exec', 'logs', 'port-forward']",
                  "items": {
                    "description": "Destination specific. For Kubernetes, it is the list of cluster roles available on that cluster",
                    "example": "['cluster-admin', 'admin', 'edit', 'view', 'exec', 'logs', 'port-forward']",
                    "type": "string"
                  },
                  "type": "array"
                },
                "uniqueID": {
                  "description": "Unique ID generated by the connector",
                  "example": "94c2c570a20311180ec325fd56",
                  "type": "string"
                },
                "updated": {
                  "description": "Time destination was updated",
                  "example": "2022-12-01T19:48:55Z",
                  "format": "date-time",
                  "type": "string"
                },
                "version": {
                  "description": "Application version of the connector for this destination",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "limit": {
            "description": "Number of objects per page",
            "example": "100",
            "format": "int",
            "type": "integer"
          },
          "page": {
            "description": "Page number retrieved",
            "example": "1",
            "format": "int",
            "type": "integer"
          },
          "totalCount": {
            "description": "Total number of objects",
            "example": "485",
            "format": "int",
            "type": "integer"
          },
          "totalPages": {
            "description": "Total number of pages",
            "example": "5",
            "format": "int",
            "type": "integer"
          }
        }
      },
      "ListResponse_Grant": {
        "properties": {
          "count": {
            "description": "Total number of items on the current page",
            "example": "100",
            "format": "int",
            "type": "integer"
          },
          "items": {
            "items": {
              "properties": {
                "created": {
                  "description": "formatted as an RFC3339 date-time",
                  "example": "2022-03-14T09:48:00Z",
                  "format": "date-time",
                  "type": "string"
                },
                "createdBy": {
                  "description": "id of the user that created the grant",
                  "example": "4yJ3n3D8E2",
                  "format": "uid",
                  "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
                  "type": "string"
                },
                "group": {
                  "description": "GroupID for a group being granted access",
                  "example": "3zMaadcd2U",
                  "format": "uid",
                  "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
                  "type": "string"
                },
                "id": {
                  "description": "ID of grant created",
                  "example": "3w9XyTrkzk",
                  "format": "uid",
                  "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
                  "type": "string"
                },
                "privilege": {
                  "description": "a role or permission",
                  "example": "admin",
                  "type": "string"
                },
                "resource": {
                  "description": "a resource name in Infra's Universal Resource Notation",
                  "example": "production.namespace",
                  "type": "string"
                },
                "updated": {
                  "description": "formatted as an RFC3339 date-time",
                  "example": "2022-03-14T09:48:00Z",
                  "format": "date-time",
                  "type": "string"
                },
                "user": {
                  "description": "UserID for a user being granted access",
                  "example": "6hNnjfjVcc",
                  "format": "uid",
                  "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "limit": {
            "description": "Number of objects per page",
            "example": "100",
            "format": "int",
            "type": "integer"
          },
          "page": {
            "description": "Page number retrieved",
            "example": "1",
            "format": "int",
            "type": "integer"
          },
          "totalCount": {
            "description": "Total number of objects",
            "example": "485",
            "format": "int",
            "type": "integer"
          },
          "totalPages": {
            "description": "Total number of pages",
            "example": "5",
            "format": "int",
            "type": "integer"
          }
        }
      },
      "ListResponse_Group": {
        "properties": {
          "count": {
            "description": "Total number of items on the current page",
            "example": "100",
            "format": "int",
            "type": "integer"
          },
          "items": {
            "items": {
              "properties": {
                "created": {
                  "description": "Date the group was created",
                  "example": "2022-03-14T09:48:00Z",
                  "format": "date-time",
                  "type": "string"
                },
                "id": {
                  "description": "Group ID",
                  "example": "gauEdoYCEU",
                  "format": "uid",
                  "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
                  "type": "string"
                },
                "name": {
                  "description": "Name of the group",
                  "example": "admins",
                  "type": "string"
                },
                "totalUsers": {
                  "description": "Total number of users in the group",
                  "example": "14",
                  "format": "int",
                  "type": "integer"
                },
                "updated": {
                  "description": "Date the group was updated",
                  "example": "2022-03-14T09:48:00Z",
                  "format": "date-time",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "limit": {
            "description": "Number of objects per page",
            "example": "100",
            "format": "int",
            "type": "integer"
          },
          "page": {
            "description": "Page number retrieved",
            "example": "1",
            "format": "int",
            "type": "integer"
          },
          "totalCount": {
            "description": "Total number of objects",
            "example": "485",
            "format": "int",
            "type": "integer"
          },
          "totalPages": {
            "description": "Total number of pages",
            "example": "5",
            "format": "int",
            "type": "integer"
          }
        }
      },
      "ListResponse_Organization": {
        "properties": {
          "count": {
            "description": "Total number of items on the current page",
            "example": "100",
            "format": "int",
            "type": "integer"
          },
          "items": {
            "items": {
              "properties": {
                "allowedDomains": {
                  "description": "domains which can be used to login to this organization",
                  "example": "['example.com', 'infrahq.com']",
                  "items": {
                    "description": "domains which can be used to login to this organization",
                    "example": "['example.com', 'infrahq.com']",
                    "type": "string"
                  },
                  "type": "array"
                },
                "created": {
                  "description": "formatted as an RFC3339 date-time",
                  "example": "2022-03-14T09:48:00Z",
                  "format": "date-time",
                  "type": "string"
                },
                "domain": {
                  "type": "string"
                },
                "id": {
                  "example": "4yJ3n3D8E2",
                  "format": "uid",
                  "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "updated": {
                  "description": "formatted as an RFC3339 date-time",
                  "example": "2022-03-14T09:48:00Z",
                  "format": "date-time",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "limit": {
            "description": "Number of objects per page",
            "example": "100",
            "format": "int",
            "type": "integer"
          },
          "page": {
            "description": "Page number retrieved",
            "example": "1",
            "format": "int",
            "type": "integer"
          },
          "totalCount": {
            "description": "Total number of objects",
            "example": "485",
            "format": "int",
            "type": "integer"
          },
          "totalPages": {
            "description": "Total number of pages",
            "example": "5",
            "format": "int",
            "type": "integer"
          }
        }
      },
      "ListResponse_Provider": {
        "properties": {
          "count": {
            "description": "Total number of items on the current page",
            "example": "100",
            "format": "int",
            "type": "integer"
          },
          "items": {
            "items": {
              "properties": {
                "authURL": {
                  "description": "Authorize endpoint for the OIDC provider",
                  "example": "https://example.com/oauth2/v1/authorize",
                  "type": "string"
                },
                "clientID": {
                  "description": "Client ID for the OIDC provider",
                  "example": "0oapn0qwiQPiMIyR35d6",
                  "type": "string"
                },
                "created": {
                  "description": "formatted as an RFC3339 date-time",
                  "example": "2022-03-14T09:48:00Z",
                  "format": "date-time",
                  "type": "string"
                },
                "id": {
                  "description": "Provider ID",
                  "example": "4yJ3n3D8E2",
                  "format": "uid",
                  "pattern": "[1-9a-km-zA-HJ-NP-Z]{1,11}",
                  "type": "string"
                },
                "kind": {
                  "description": "Kind of provider",
                  "example": "oidc",
                  "type": "string"
                },
                "name": {
                  "description": "Name of the provider",
                  "example": "okta",
                  "type": "string"
                },
                "scopes": {
                  "description": "Scopes set in 

# --- truncated at 32 KB (220 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/infra/refs/heads/main/openapi/infra-openapi-original.json