openapi: 3.1.0 info: title: Freestyle Identity API version: 0.1.0 description: "Identity and access management for end users and agents \u2014 identities, access tokens, repository permissions,\ \ VM permissions, and bearer-token whoami/background-request lookup." contact: name: Ben email: ben@freestyle.sh license: name: Closed Source servers: - url: https://api.freestyle.sh description: Production tags: - name: Identity description: APIs for managing identities and access tokens. paths: /auth/v1/background-requests/{request_id}: get: tags: - Auth summary: Get Background Request Result description: Replay the stored response for a backgrounded request when it finishes. operationId: handle_get_background_request parameters: - name: request_id in: path description: Background request ID required: true schema: $ref: '#/components/schemas/RequestId' responses: '200': description: Completed request response replayed '202': description: Background request still running content: application/json: schema: $ref: '#/components/schemas/BackgroundRequestPendingResponse' '404': description: Background request not found or expired content: application/json: schema: $ref: '#/components/schemas/BackgroundRequestErrorResponse' /auth/v1/whoami: get: tags: - Auth summary: Get Current User description: Returns information about the currently authenticated user or identity. operationId: handle_whoami responses: '200': description: Current authenticated user information content: application/json: schema: $ref: '#/components/schemas/WhoAmIResponse' /identity/v1/identities: get: tags: - Identity summary: List Identities description: List identities created by your account. operationId: handle_list_identities parameters: - name: limit in: query required: false schema: type: - integer - 'null' format: int64 minimum: 0 - name: offset in: query required: false schema: type: - integer - 'null' format: int64 minimum: 0 - name: includeManaged in: query required: false schema: type: - boolean - 'null' responses: '200': description: List of identities content: application/json: schema: $ref: '#/components/schemas/ListIdentitiesSuccess' post: tags: - Identity summary: Create an Identity description: Create an identity. This identity will be used to authenticate with the Git server. operationId: handle_create_identity responses: '200': description: Identity created successfully content: application/json: schema: $ref: '#/components/schemas/FreestyleIdentity' /identity/v1/identities/{identity}: delete: tags: - Identity summary: Delete an Identity description: Delete an identity. This will revoke all permissions granted to this identity. operationId: handle_delete_identity parameters: - name: identity in: path required: true schema: type: string format: uuid responses: '200': description: Identity deleted content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' /identity/v1/identities/{identity}/permissions/git: get: tags: - Identity summary: List Repository Permissions for an Identity description: List repository permissions for an identity. This will return a list of repositories that the identity has access to. operationId: handle_list_git_permissions parameters: - name: identity in: path required: true schema: type: string format: uuid - name: limit in: query description: Maximum number of repositories to return required: false schema: type: integer format: int64 minimum: 0 - name: offset in: query description: Offset for the list of repositories required: false schema: type: integer format: int64 minimum: 0 responses: '200': description: Permission list content: application/json: schema: $ref: '#/components/schemas/ListGitPermissionSuccess' /identity/v1/identities/{identity}/permissions/git/{repo}: get: tags: - Identity summary: Get the Git Permission of an Identity on a Repository description: Get the permission of an identity on a repository. This will return the access level of the identity on the repository. operationId: handle_describe_git_permission parameters: - name: identity in: path description: The git identity ID required: true schema: type: string format: uuid - name: repo in: path description: The git repository ID required: true schema: type: string format: uuid responses: '200': description: Permission info content: application/json: schema: $ref: '#/components/schemas/DescribeGitPermissionSuccess' put: tags: - Identity summary: Update a Git Repository Permission for an Identity description: Update a permission for an identity on a repository operationId: handle_update_git_permission parameters: - name: identity in: path description: The git identity ID required: true schema: type: string format: uuid - name: repo in: path description: The git repository ID required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateGitPermissionRequest' required: true responses: '200': description: Permission updated successfully content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' post: tags: - Identity summary: Grant a Git Repository Permission to an Identity description: Grant a permission to an identity on a repository operationId: handle_grant_git_permission parameters: - name: identity in: path description: The git identity ID required: true schema: type: string format: uuid - name: repo in: path description: The git repository ID required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/GrantGitPermissionRequest' required: true responses: '200': description: Permission granted successfully content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' delete: tags: - Identity summary: Revoke Git Repository Permission From an Identity description: Revoke a permission to an identity on a repository operationId: handle_revoke_git_permission parameters: - name: identity in: path description: The git identity ID required: true schema: type: string format: uuid - name: repo in: path description: The git repository ID required: true schema: type: string format: uuid responses: '200': description: Permission revoked successfully content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' /identity/v1/identities/{identity}/permissions/vm: get: tags: - Identity summary: List VM Permissions for an Identity description: List all VM permissions granted to a specific Git identity operationId: handle_list_vm_permissions parameters: - name: identity in: path required: true schema: type: string format: uuid - name: limit in: query required: false schema: type: - integer - 'null' format: int64 minimum: 0 - name: offset in: query required: false schema: type: - integer - 'null' format: int64 minimum: 0 responses: '200': description: List of VM permissions content: application/json: schema: $ref: '#/components/schemas/ListVmPermissionsSuccess' /identity/v1/identities/{identity}/permissions/vm/{vm_id}: get: tags: - Identity summary: Get VM Permission Details description: Get the details of a VM permission for a specific identity and VM operationId: handle_describe_vm_permission parameters: - name: identity in: path description: The git identity ID required: true schema: type: string format: uuid - name: vm_id in: path description: The VM ID required: true schema: type: string responses: '200': description: VM permission details content: application/json: schema: $ref: '#/components/schemas/VmPermission' put: tags: - Identity summary: Update Allowed Users for VM Permission description: Update the list of allowed users for a VM permission. Set to null to allow all users, or provide a list to restrict access. operationId: handle_update_allowed_users parameters: - name: identity in: path description: The git identity ID required: true schema: type: string format: uuid - name: vm_id in: path description: The VM ID required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAllowedUsersRequestBody' required: true responses: '200': description: Allowed users updated successfully content: application/json: schema: $ref: '#/components/schemas/VmPermission' post: tags: - Identity summary: Grant VM Permission to an Identity for a VM description: Grant VM access permission to an identity for a specific VM. Optionally restrict access to specific Linux users. operationId: handle_grant_vm_permission parameters: - name: identity in: path description: The git identity ID required: true schema: type: string format: uuid - name: vm_id in: path description: The VM ID required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/GrantVmPermissionRequest' required: true responses: '200': description: VM permission granted successfully content: application/json: schema: $ref: '#/components/schemas/VmPermission' delete: tags: - Identity summary: Revoke VM Permission From an Identity for a VM description: Revoke VM permission from an identity for a specific VM operationId: handle_revoke_vm_permission parameters: - name: identity in: path description: The git identity ID required: true schema: type: string format: uuid - name: vm_id in: path description: The VM ID required: true schema: type: string responses: '200': description: VM permission revoked successfully content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' /identity/v1/identities/{identity}/tokens: get: tags: - Identity summary: List Access Tokens for an Identity description: List access tokens for an identity operationId: handle_list_git_tokens parameters: - name: identity in: path required: true schema: type: string format: uuid responses: '200': description: Token list content: application/json: schema: $ref: '#/components/schemas/ListGitTokensSuccess' post: tags: - Identity summary: Create an Access Token for an Identity description: Create an access token for an identity operationId: handle_create_git_token parameters: - name: identity in: path required: true schema: type: string format: uuid responses: '200': description: Token created successfully content: application/json: schema: $ref: '#/components/schemas/CreatedToken' /identity/v1/identities/{identity}/tokens/{token}: delete: tags: - Identity summary: Revoke an Access Token for an Identity description: Revoke an access token for an identity operationId: handle_revoke_git_token parameters: - name: identity in: path required: true schema: type: string format: uuid - name: token in: path required: true schema: type: string format: uuid responses: '200': description: Token revoked content: application/json: schema: $ref: '#/components/schemas/EmptyResponse' components: securitySchemes: bearerAuth: type: http scheme: bearer schemas: ListIdentitiesSuccess: type: object required: - identities - offset - total properties: identities: type: array items: $ref: '#/components/schemas/FreestyleIdentity' offset: type: integer format: int64 minimum: 0 total: type: integer format: int64 minimum: 0 BackgroundRequestErrorResponse: type: object required: - message properties: message: type: string ListGitTokensSuccess: type: object required: - tokens properties: tokens: type: array items: $ref: '#/components/schemas/AccessTokenInfo' DescribeGitPermissionSuccess: type: object required: - identity - repo properties: identity: type: string format: uuid repo: type: string format: uuid accessLevel: oneOf: - type: 'null' - $ref: '#/components/schemas/AccessLevel' BackgroundRequestPendingResponse: type: object required: - requestId - status properties: requestId: $ref: '#/components/schemas/RequestId' status: type: string AccessTokenInfo: type: object required: - id properties: id: type: string format: uuid FreestyleIdentity: type: object required: - id - managed properties: id: type: string format: uuid managed: type: boolean ListVmPermissionsSuccess: type: object required: - permissions - offset - total properties: permissions: type: array items: $ref: '#/components/schemas/VmPermission' offset: type: integer format: int64 minimum: 0 total: type: integer format: int64 minimum: 0 AccessibleRepository: type: object description: Identical to [`RepositoryInfo`], but with the permissions field added. required: - id - accountId - permissions - visibility properties: id: type: string format: uuid name: type: - string - 'null' accountId: type: string format: uuid permissions: $ref: '#/components/schemas/AccessLevel' visibility: $ref: '#/components/schemas/Visibility' ListGitPermissionSuccess: type: object required: - repositories properties: repositories: type: array items: $ref: '#/components/schemas/AccessibleRepository' AccessLevel: type: string enum: - read - write RequestId: type: string description: "Branded request identifier \u2014 `ri-<20 lowercase alphanumeric chars>` for newly\nminted IDs. The wrapped\ \ string is otherwise opaque, so legacy UUID-formatted\nIDs (from in-flight requests during rollout) round-trip unchanged." UpdateGitPermissionRequest: type: object required: - permission properties: permission: $ref: '#/components/schemas/AccessLevel' GrantGitPermissionRequest: type: object required: - permission properties: permission: $ref: '#/components/schemas/AccessLevel' VmPermission: type: object description: Full VM permission record required: - id - vmId - identityId - grantedAt - grantedBy properties: id: type: string format: uuid vmId: type: string identityId: type: string format: uuid allowedUsers: type: - array - 'null' items: type: string grantedAt: type: string format: date-time grantedBy: type: string format: uuid GrantVmPermissionRequest: type: object properties: allowedUsers: type: - array - 'null' items: type: string description: 'List of allowed Linux users. If null, identity can SSH as any user. If specified, identity can only SSH as users in this list.' Visibility: type: string enum: - public - private EmptyResponse: type: object WhoAmIResponse: type: object required: - accountId properties: accountId: type: string format: uuid identityId: type: - string - 'null' format: uuid UpdateAllowedUsersRequestBody: type: object properties: allowedUsers: type: - array - 'null' items: type: string description: 'List of allowed Linux users. If null, identity can SSH as any user. If specified, identity can only SSH as users in this list.' CreatedToken: type: object required: - id - token properties: id: type: string format: uuid token: type: string security: - bearerAuth: []