The Guests API from Tower — 3 operation(s) for guests.
openapi: 3.1.0
info:
contact:
email: hello@tower.dev
name: Tower Computing GmbH
url: https://tower.dev
description: REST API to interact with Tower Services.
termsOfService: https://tower.dev/terms
title: Tower Accounts Guests API
version: v0.11.16
servers:
- url: https://api.tower.dev/v1
tags:
- name: Guests
paths:
/guests:
get:
description: Lists all guests for the current account, optionally filtered by app.
operationId: list-guests
parameters:
- description: Filter guests by app name.
explode: false
in: query
name: app
schema:
description: Filter guests by app name.
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListGuestsResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps
- APIKeyAuth:
- apps
summary: List guests
tags:
- Guests
post:
description: Creates a new guest with access to a specific externally accessible app and returns a login URL to share with them.
operationId: create-guest
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGuestParams'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateGuestResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps:update
- APIKeyAuth:
- apps:update
summary: Create guest
tags:
- Guests
/guests/{guest_id}:
delete:
description: Deletes a guest and revokes their access. Any active sessions will be invalidated.
operationId: delete-guest
parameters:
- description: The ID of the guest to delete.
in: path
name: guest_id
required: true
schema:
description: The ID of the guest to delete.
type: string
responses:
'204':
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteGuestOutputBody'
description: No Content
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps
- APIKeyAuth:
- apps
summary: Delete guest
tags:
- Guests
/guests/{guest_id}/login-url:
post:
description: Creates a new login URL for an existing guest. Use this if the previous URL expired or was compromised.
operationId: regenerate-guest-login-url
parameters:
- description: The ID of the guest to regenerate the login URL for.
in: path
name: guest_id
required: true
schema:
description: The ID of the guest to regenerate the login URL for.
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RegenerateGuestLoginURLParams'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RegenerateGuestLoginURLResponse'
description: OK
default:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorModel'
description: Error
security:
- AccessTokenAuth:
- apps
- APIKeyAuth:
- apps
summary: Regenerate guest login URL
tags:
- Guests
components:
schemas:
RegenerateGuestLoginURLResponse:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- https://api.tower.dev/v1/schemas/RegenerateGuestLoginURLResponse.json
format: uri
readOnly: true
type: string
login_url:
description: The new login URL to share with the guest.
type: string
login_url_expires_at:
description: When the login URL expires.
format: date-time
type: string
required:
- login_url
- login_url_expires_at
type: object
CreateGuestResponse:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- https://api.tower.dev/v1/schemas/CreateGuestResponse.json
format: uri
readOnly: true
type: string
guest:
$ref: '#/components/schemas/Guest'
description: The created guest.
login_url:
description: The URL to share with the guest for logging in.
type: string
login_url_expires_at:
description: When the login URL expires.
format: date-time
type: string
required:
- guest
- login_url
- login_url_expires_at
type: object
ErrorModel:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- https://api.tower.dev/v1/schemas/ErrorModel.json
format: uri
readOnly: true
type: string
detail:
description: A human-readable explanation specific to this occurrence of the problem.
examples:
- Property foo is required but is missing.
type: string
errors:
description: Optional list of individual error details
items:
$ref: '#/components/schemas/ErrorDetail'
type: array
instance:
description: A URI reference that identifies the specific occurrence of the problem.
examples:
- https://example.com/error-log/abc123
format: uri
type: string
status:
description: HTTP status code
examples:
- 400
format: int64
type: integer
title:
description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
examples:
- Bad Request
type: string
type:
default: about:blank
description: A URI reference to human-readable documentation for the error.
examples:
- https://example.com/errors/example
format: uri
type: string
type: object
RegenerateGuestLoginURLParams:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- https://api.tower.dev/v1/schemas/RegenerateGuestLoginURLParams.json
format: uri
readOnly: true
type: string
expires_in:
default: 259200
description: The number of seconds the guest session should last. Defaults to 72 hours.
format: int64
type: integer
redirect_url:
description: Where to redirect the guest after they log in.
type: string
type: object
ListGuestsResponse:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- https://api.tower.dev/v1/schemas/ListGuestsResponse.json
format: uri
readOnly: true
type: string
guests:
description: List of guests.
items:
$ref: '#/components/schemas/Guest'
type: array
required:
- guests
type: object
CreateGuestParams:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- https://api.tower.dev/v1/schemas/CreateGuestParams.json
format: uri
readOnly: true
type: string
app:
description: The name of the externally accessible app this guest can access.
type: string
expires_in:
default: 259200
description: The number of seconds the guest session should last. Defaults to 72 hours.
format: int64
type: integer
name:
description: Optional display name for the guest.
type: string
redirect_url:
description: Where to redirect the guest after they log in. Defaults to the app's subdomain.
type: string
required:
- app
type: object
DeleteGuestOutputBody:
additionalProperties: false
properties:
$schema:
description: A URL to the JSON Schema for this object.
examples:
- https://api.tower.dev/v1/schemas/DeleteGuestOutputBody.json
format: uri
readOnly: true
type: string
type: object
ErrorDetail:
additionalProperties: false
properties:
location:
description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
type: string
message:
description: Error message text
type: string
value:
description: The value at the given location
type: object
Guest:
additionalProperties: false
properties:
app:
description: The name of the app this guest can access.
type: string
created_at:
description: When the guest was created.
format: date-time
type: string
id:
description: The unique identifier for the guest.
type: string
name:
description: Optional display name for the guest.
type: string
required:
- id
- app
- created_at
type: object
securitySchemes:
APIKeyAuth:
description: API key created by a Tower user or Tower service account to authenticate an API request.
in: header
name: X-API-Key
type: apiKey
AccessTokenAuth:
description: Access token authentication scheme which uses an access token provided by the Tower API as part of a Tower session (see documentation about creating sessions).
scheme: Bearer
type: http