> ## Documentation Index > Fetch the complete documentation index at: https://hoopdev-docs-improve-idp-sso-pages.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Get Session > Get a session by id. This endpoint returns a conditional response - When the query string `extension` is present it will return a payload containing a link to download the session ```json { "download_url": "http://127.0.0.1:8009/api/sessions//download?token=&extension=csv&newline=1&event-time=0&events=o,e", "expire_at": "2024-07-25T15:56:35.317601Z", } ``` - Fetching the endpoint without any query string returns the payload documented for this endpoint - The attribute `event_stream` will be rendered differently if the request contains the query string `event_stream` with the values `utf8` or `base64`. ```json { (...) "event_stream": ["hello world"] (...) } ``` The attribute `metrics` contains the following structure: ```json { "data_masking": { "err_count": 0, "info_types": { "EMAIL_ADDRESS": 1 }, "total_redact_count": 1, "transformed_bytes": 31 }, "event_size": 356 } ``` ## OpenAPI ````yaml https://use.hoop.dev/api/openapiv3.json get /sessions/{session_id} openapi: 3.0.3 info: contact: email: help@hoop.dev name: Help url: https://help.hoop.dev description: >- Hoop.dev is an access gateway for databases and servers with an API for packet manipulation license: name: MIT url: https://opensource.org/license/mit termsOfService: https://hoop.dev/docs/legal/tos title: Hoop Api version: 1.49.10 servers: - url: https://use.hoop.dev/api security: [] tags: - description: > Hoop implements Oauth2 and OIDC protocol to authenticate users in the system. To obtain a valid access token users need to authenticate in their own identity provider which is generated as a JSON response to the endpoint `http(s)://use.hoop.dev/api/login`. The identity provider them redirects the user to the callback endpoint containing the access token. The recommended approach of obtaining an access token is by visiting the Webapp main's page or using the **Hoop command line**. Example: ```sh hoop config create --api-url https://use.hoop.dev # save the token after authenticating at $HOME/.hoop/config.toml hoop login # show token information hoop config view --raw ``` With an access token you could use any HTTP client to interact with the documented endpoints. The token must be sent through the `Authorization` header. Example: ```sh # obtain the current configuration of the server curl https://use.hoop.dev/api/serverinfo -H "Authorization: Bearer $ACCESS_TOKEN" ``` name: Authentication - description: > Users are active and assigned to the default organization when they signup. A user could be set to an inactive state preventing it from accessing the platform, however it’s recommended to manage the state of users in the identity provider. - The `sub` claim is used as the main identifier of the user in the platform. - The profile of the user is derived from the id_token claims `email` and `name`. When a user authenticates for the first time, it performs an automatic signup that persist the profile claims along with it’s unique identifier. ​ ### Groups Groups allows defining who may access or interact with certain resources. - For connection resources it’s possible to define which groups has access to a specific connection, this is enforced when the Access Control feature is enabled. - For review resources, it’s possible to define which groups are allowed to approve an execution, this is enforced when the Review feature is enabled. > This resource could be managed manually via Webapp or propagated by the identity provider via ID Token. In this mode, groups are sync when a user performs a login. ### Roles - The `admin` group is a special role that grants full access to all resources This role should be granted to users that are responsible for managing the Gateway. All other users are regular, meaning that they can access their own resources and interact with connections. name: User Management - description: Routes used to manage and obtain information about the runtime server. name: Server Management - description: Features available in the gateway. See also **Plugin** resources. name: Features - description: >- Proxy manager endpoints controls how clients connect via gRPC in the gateway. These endpoints are meant to be used when a client is initialized via `hoop proxy-manager`. name: Proxy Manager - name: Connections - name: Agents - name: Runbooks - name: Guard Rails - name: Reviews - name: Sessions - name: Organization Management - name: Reports paths: /sessions/{session_id}: get: tags: - Sessions summary: Get Session description: > Get a session by id. This endpoint returns a conditional response - When the query string `extension` is present it will return a payload containing a link to download the session ```json { "download_url": "http://127.0.0.1:8009/api/sessions//download?token=&extension=csv&newline=1&event-time=0&events=o,e", "expire_at": "2024-07-25T15:56:35.317601Z", } ``` - Fetching the endpoint without any query string returns the payload documented for this endpoint - The attribute `event_stream` will be rendered differently if the request contains the query string `event_stream` with the values `utf8` or `base64`. ```json { (...) "event_stream": ["hello world"] (...) } ``` The attribute `metrics` contains the following structure: ```json { "data_masking": { "err_count": 0, "info_types": { "EMAIL_ADDRESS": 1 }, "total_redact_count": 1, "transformed_bytes": 31 }, "event_size": 356 } ``` parameters: - description: >- Construct the file content adding the event time as prefix when parsing each event in: query name: event-time schema: default: '0' enum: - '0' - '1' type: string - description: >- Parse available options for the event stream * `utf8` - parse the session output (o) and error (e) events as utf-8 content in the session payload * `base64` - parse the session output (o) and error (e) events as base64 content in the session payload * `raw-queries` - encode each event stream parsing the input of queries based on the database wire protocol (available databases: postgres) in: query name: event_stream schema: enum: - utf8 - base64 - raw-queries type: string x-enum-varnames: - SessionEventStreamUTF8Type - SessionEventStreamBase64Type - SessionEventStreamRawQueriesType - description: |- Choose the type of events to include * `i` - Input (stdin) * `o` - Output (stdout) * `e` - Error (stderr) in: query name: events schema: items: type: string type: array - description: Expand the given attributes in: query name: expand schema: enum: - event_stream - session_input type: string - description: |- The file extension to donwload the session as a file content. * `csv` - it will parse the content to format in csv format * `json` - it will parse the content as a json stream. * `` - No special parsing is applied in: query name: extension schema: type: string - description: >- Construct the file content adding a break line when parsing each event in: query name: new_line schema: default: '0' enum: - '0' - '1' type: string - description: The id of the resource in: path name: session_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/openapi.Session' description: OK '403': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Not Found '422': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Internal Server Error components: schemas: openapi.Session: properties: connection: description: The connection name of this resource example: pgdemo type: string connection_subtype: description: The subtype of the connection example: postgres type: string connection_tags: additionalProperties: type: string description: The tags of the connection resource example: team: banking;environment:prod type: object end_date: description: >- When the execution ended. A null value indicates the session is still running example: '2024-07-25T15:56:35.361101Z' type: string event_size: description: >- The stored resource size in bytes. When any parsing is applied to the request the value display the computed parsed size. The pre-computed size will be available in the attribute `metrics.event_size` example: 569 type: integer event_stream: description: >- The stream containing the output of the execution in the following format `[[0.268589438, "i", "ZW52"], ...]` * `` - relative time in miliseconds to start_date * `` - the event type as string (i: input, o: output e: output-error) * `` - the content of the session encoded as base64 string items: type: integer type: array exit_code: description: The Linux exit code if it's available type: integer id: description: The resource unique identifier example: 1CBC8DB5-FBF8-4293-8E35-59A6EEA40207 format: uuid type: string integrations_metadata: additionalProperties: {} description: >- Metadata attributes related to integrations with third party services type: object labels: allOf: - $ref: '#/components/schemas/openapi.SessionLabelsType' description: DEPRECATED in flavor of metrics and metadata metadata: additionalProperties: {} type: object metrics: additionalProperties: {} description: Refactor to use a struct type: object org_id: description: The organization unique identifier example: 0CD7F941-2BB8-4F9F-93B0-11620D4652AB format: uuid type: string review: allOf: - $ref: '#/components/schemas/openapi.SessionReview' description: >- Review of this session. In case the review doesn't exist this field will be null script: allOf: - $ref: '#/components/schemas/openapi.SessionScriptType' description: The input of the session. This value is only set for the verb `exec` example: data: SELECT NOW() script_size: description: The input size of the session in bytes example: 12 type: integer start_date: description: When the execution started example: '2024-07-25T15:56:35.317601Z' type: string status: allOf: - $ref: '#/components/schemas/openapi.SessionStatusType' description: >- Status of the resource * ready - the resource is ready to be executed, after being approved by a user * open - the session started and it's running * done - the session has finished type: description: The connection type of this resource example: database type: string user: description: The user email of the resource type: string user_id: description: The user subject identifier of the resource example: nJ1xV3ASWGTi7L8Y6zvnKqxNlnZM2TxV1bRdc0706vZ type: string user_name: description: The user display name of this resource example: John Wick type: string verb: description: >- Verb is how the client has interacted with this resource * exec - Is an ad-hoc shell execution * connect - Interactive execution, protocol port forwarding or interactive shell session enum: - connect - exec type: string type: object openapi.HTTPError: properties: message: example: the error description type: string type: object openapi.SessionLabelsType: additionalProperties: type: string type: object openapi.SessionReview: properties: access_duration: default: 1800000000000 description: >- The amount of time (nanoseconds) to allow access to the connection. It's valid only for `jit` type reviews example: 0 readOnly: true type: integer created_at: description: The time the resource was created example: '2024-07-25T15:56:35.317601Z' readOnly: true type: string id: description: Resource identifier example: 9F9745B4-C77B-4D52-84D3-E24F67E3623C format: uuid readOnly: true type: string review_groups_data: description: Contains the groups that requires to approve this review items: $ref: '#/components/schemas/openapi.ReviewGroup' readOnly: true type: array revoke_at: description: The time when this review was revoked example: '' readOnly: true type: string status: allOf: - $ref: '#/components/schemas/openapi.ReviewStatusType' description: |- The status of the review * PENDING - The resource is waiting to be reviewed * APPROVED - The resource is fully approved * REJECTED - The resource is fully rejected * REVOKED - The resource was revoked after being approved * PROCESSING - The review is being executed * EXECUTED - The review was executed * UNKNOWN - Unable to know the status of the review time_window: allOf: - $ref: '#/components/schemas/openapi.ReviewSessionTimeWindow' description: The time window configuration that can execute the session readOnly: true type: allOf: - $ref: '#/components/schemas/openapi.ReviewType' description: |- The type of the review * onetime - Represents a one time execution * jit - Represents a time based review enum: - onetime - jit readOnly: true type: object openapi.SessionScriptType: additionalProperties: type: string type: object openapi.SessionStatusType: enum: - open - ready - done type: string openapi.ReviewGroup: properties: forced_review: description: Indicates if this group is forcing the review example: false readOnly: true type: boolean group: description: The group to approve this review example: sre readOnly: true type: string id: description: The resource identifier example: 20A5AABE-C35D-4F04-A5A7-C856EE6C7703 format: uuid readOnly: true type: string review_date: description: The date which this review was performed example: '2024-07-25T19:36:41Z' readOnly: true type: string reviewed_by: allOf: - $ref: '#/components/schemas/openapi.ReviewOwner' description: The review owner readOnly: true status: allOf: - $ref: '#/components/schemas/openapi.ReviewRequestStatusType' description: |- The reviewed status * APPROVED - Approve the review resource * REJECTED - Reject the review resource * REVOKED - Revoke an approved review example: APPROVED type: object openapi.ReviewStatusType: enum: - PENDING - APPROVED - REJECTED - REVOKED - PROCESSING - EXECUTED - UNKNOWN type: string openapi.ReviewSessionTimeWindow: properties: configuration: additionalProperties: type: string example: end_time: '18:00' start_time: '09:00' type: object type: allOf: - $ref: '#/components/schemas/openapi.ReviewTimeWindowType' enum: - time_range required: - configuration - type type: object openapi.ReviewType: enum: - jit - onetime type: string openapi.ReviewOwner: properties: email: description: The email of the owner example: john.wick@bad.org readOnly: true type: string id: description: The resource identifier example: D5BFA2DD-7A09-40AE-AFEB-C95787BA9E90 format: uuid readOnly: true type: string name: description: The display name of the owner example: John Wick readOnly: true type: string slack_id: description: The Slack ID of the owner example: U053ELZHB53 readOnly: true type: string type: object openapi.ReviewRequestStatusType: enum: - APPROVED - REJECTED - REVOKED type: string openapi.ReviewTimeWindowType: enum: - time_range type: string ````