---
title: "Establish session"
method: POST
path: "/handshake"
---

# Establish session

`POST /handshake`

## Request

- Base URL: `http://localhost:21721`
- URL: `http://localhost:21721/handshake`
- Auth: none required

Prior to sending requests to the API, you first have to establish a new API session via the handshake endpoint.
In the response you will receive a session token that you can use to authenticate during this session.

This is done so that the daemon knows what kind of clients are connected and can manage individual capabilities for clients.
If your client is running on the same system as the daemon, you can choose the local authentication method to avoid having to deal with API keys.
If your client does not have file system access, e.g. if it is running remotely, then you have to use an API key.

Note that for development you can also turn off the required authentication in the XPipe settings menu, allowing you to send unauthenticated requests.

## Request body

- HandshakeRequest
  - `auth` union, required
    - ApiKey: API key authentication
      - `type` string, required
      - `key` string, required: The API key
    - Local: Authentication method for local applications. Uses file system access as proof of authentication. You can find the authentication file at: - %TEMP%\xpipe\beacon-auth on Windows - $TMP/xpipe/$USER/beacon-auth on Linux - $TMPDIR/xpipe/beacon-auth on macOS For the PTB releases the dir name is changed to xpipe-ptb to prevent collisions.
      - `type` string, required
      - `authFileContent` string, required: The contents of the local file beacon-auth. This file is automatically generated when XPipe starts.
  - `client` ClientInformation, required
    - `type` string, required

## Response `200`

The handshake was successful. The returned token can be used for authentication in this session. The token is valid as long as XPipe is running.

- HandshakeResponse
  - `sessionToken` string, required: The generated bearer token that can be used for authentication in this session

## Other responses

- `400`: Bad request. Please check error message and your parameters.
- `500`: Internal error.

---

[API](https://skmtc.dev/xpipe/apis/xpipe-api-documentation.md) - [All operations](https://skmtc.dev/xpipe/apis/xpipe-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/xpipe/apis/xpipe-api-documentation/revisions/cc0e84caab21?raw)