# Connection flow

> Connect players through the Allocations service and Relay servers.

The connection flow is the process by which the [Allocations service](./allocation-service.md) reserves slots on a [Relay server](../networking/relay-servers) to group players into a match. The process involves two types of [players](../players): a host player and joining players. The following list describes the high-level steps involved in the connection process.

```mermaid
sequenceDiagram
    actor Host as Host player
    participant Alloc as Relay allocations service
    participant Relay as Relay server
    actor Joiner as Joining player

    Host->>Alloc: 1. Request allocation (max connections, optional region)
    Alloc->>Relay: 2. Select Relay server & reserve slot
    Relay-->>Alloc: Secret key, IP, ports, connection data
    Alloc-->>Host: 3. Send connection data
    Host->>Relay: 4. BIND message
    Relay-->>Host: BIND_RECEIVED
    Host->>Alloc: 5. Request join code
    Alloc-->>Host: 6. Return join code
    Host->>Joiner: 7. Share join code (out of band)
    Joiner->>Alloc: 8. Use join code (join request)
    Alloc-->>Joiner: 9. Send connection data
    Joiner->>Relay: 10. BIND message
    Relay-->>Joiner: BIND_RECEIVED
    Joiner->>Host: 11. Send connection request (via Relay)
```

1. [The host player requests allocation](#1)
2. [The Allocations service selects a Relay server](#2)
3. [The Allocations service sends the connection data to the host player](#3)
4. [The host player binds to the Relay server](#4)
5. [The host player requests a join code](#5)
6. [The Allocations service returns a join code to the host player](#6)
7. [The host player shares the join code with joining players](#7)
8. [The joining players use the join code](#8)
9. [The Allocations service sends connection data to the joining player](#9)
10. [The joining player binds to the Relay server](#10)
11. [The joining player sends connection request](#11)

## The host player requests an allocation##1

The host player initiates the connection flow by requesting an allocation from the Allocations service. The allocation request includes the maximum number of connections the allocation can allow. It can also include a specific [region](../networking/locations-and-regions). If the request doesn’t include a region, the Allocations service uses [QoS](../networking/qos) to select the best region for the request.

## The Allocations service selects a Relay server##2

The Allocations service receives the host player's request and selects an appropriate Relay server. The Relay server selection depends on the maximum connections allowed and the region.

When the Allocations service finds a Relay server, it reserves a space on the Relay server for the session. At this point, the Relay server also generates a unique secret key. The Relay server returns the secret key to the Allocations service, in addition to the Relay server IP, the Relay server ports, and the connection data.

## The Allocations service sends the connection data to the host player##3

The Allocations service sends the Relay server connection data to the host player's game client.

## The host player binds to the Relay server##4

The host sends a [`BIND` message](./relay-message-protocol.md#bind) to the selected Relay server using the data received from the response from the allocation request. The `BIND` message has the connection data, the accept mode, nonce, and HMAC. If the host doesn’t send the bind to the Relay server within 60 seconds after making the allocation, the allocation times out from inactivity.

If the information in the request is accurate, the Relay server acknowledges the bind request by sending a [`BIND_RECEIVED` message](./relay-message-protocol.md#bind-rec) back to the host client.

> **Note:**
>
> You typically send `BIND` messages after calling the allocate and join APIs, which retrieve the Relay server’s destination address for use with the `BIND` message.

## The host player requests a join code##5

Once bound to the Relay server, the host player can request a join code from the Allocations service.

## The Allocations service returns a join code to the host player##6

The Allocations service generates and returns a join code to the host player. The join code the Allocations service returns uniquely represents the host player’s allocation to the Relay server, and allows joining players to bind to the same Relay server and connect to the host player.

## The host player shares the join code with joining players##7

The host player shares the unique join code with other players through any method, including verbally, through a text message, or through a [Lobby](/lobby/.md). The join codes are short and easy to remember to ease sharing.

The players that use the join code with a join request to the Allocations service become the joining players.

> **Note:**
>
> Any number of joining players can use the same join code so long as the number doesn't exceed the maximum number of connections specified in the initial allocation request.

## The joining players use the join code##8

The joining players use the join code from the host player to send a join request to the Allocations service.

> **Note:**
>
> A “join” is when a joining player (a non-host player) client joins the host client’s session. Under the hood, it’s another allocate call to the Relay backend service.

## The Allocations service sends connection data to the joining player##9

The Allocations service uses the join code to look up the host player’s allocation and returns the data to the joining players.

The response from the Allocations service has the Relay server IP address, the Relay server port, the secret key, the encrypted joining player’s connection data, the joining player’s allocation ID, and the encrypted host connection data. The joining player can then use the secret key to decrypt and use the host connection data to connect to the host.

## The joining player binds to the Relay server##10

The joining player sends a [`BIND` message](./relay-message-protocol.md#bind) to the Relay server using its connection data it received from the response to the join request made to the Allocations service.

Upon success, the Relay server acknowledges by sending a[`BIND_RECEIVED` message](./relay-message-protocol.md#bind-rec) to the joining player's game client.

> **Note:**
>
> You should typically send `BIND` messages after calling the allocate and join APIs, which retrieve the Relay server’s destination address for use with the `BIND` message.

## The joining player sends a connection request##11

Once bound to the same Relay server as the host player, the joining player then sends a connection request to the host player. If the connection request is successful, the joining player and the host player can send data to each other through the Relay server.