Create a join address

A join address gives one of your servers hosted here a name that players type in their game, such as survival-smp.coritan.gg, instead of an IP address and port. Create one when a server has no join address yet, or when you want another name for it (How join addresses work). To give a name to a server you run elsewhere, connect it as an external server instead.

• You need a server hosted here (Order a server).
• The join address forwards to the server's primary address and port, which the Network card on the server's Settings tab shows (Server settings). The game must listen on that port, so make the game's port primary first if it is not (Make another port primary). A TCP service can forward to another of the server's ports when you create it with the API (With the API).
• For a Java server with Bedrock crossplay, create a Minecraft Java join address. Bedrock players join at the same name, on port 19132.

On a Minecraft server with no join address, you can start from its Settings tab: select Give players a name to join… on the Network card. The Create a join address page opens with the edition and server chosen, and Settings as its back link. Continue from step 3.

1. In the dashboard, go to Game Shield and select Create a join address. The Create a join address page opens, at /dashboard/proxies/game/new. Its back link returns to the list you came from.

2. In the Edition section, choose Minecraft Java, Minecraft Bedrock or TCP service (Editions and ports). It starts on Minecraft Java.

3. In the Server section, keep A server hosted here and choose the server. The list shows each server's name with its address and port.

4. In the Join name section, type the name in Join subdomain, such as survival-smp. The field checks the name as you type, and shows survival-smp.coritan.gg is available. when it is free (Name rules).

   To use a generated name instead, select Suggest a name, then select one of the five names it offers. Choosing one also fills in Display name when it is empty.

5. Optionally, enter a Display name of up to 100 characters. The dashboard shows it, and you can change it later as the Server name on the Server list tab. Without one, the join address uses its subdomain.

6. To send each player's real IP address, select Show options in the Advanced section and turn on PROXY protocol. Turn it on only when the server expects a PROXY protocol version 2 header on each connection (What your server receives). A Bedrock join address cannot use it, so its page has no Advanced section.

   Important

   You cannot change PROXY protocol once the join address exists. A server that does not expect the header refuses every player.

7. Select Create join address. The button stays unavailable until the name is free, and the note beside it says why. A refusal keeps everything you entered.

A join address for a server hosted here costs nothing, and the Your join address card beside the form says Free. Select Cancel, or the back link, to leave without creating it.

While your account has no server hosted here, A server hosted here reads No servers on your account yet. and the page offers Order a server. Choose A server elsewhere to connect a server you run elsewhere: the button becomes Continue to External Server, which opens the order page for one. When your account cannot connect a server elsewhere either, the page says You have no server to give a name and offers Order a server.

For a TCP service, the page notes that Coritan gives the join address a port of its own in the server's region. You see the port once the join address exists.

Older links that end in ?new=join, such as the one on Coritan's public Game Shield page, open this page too.

A join address's name is one label under the join domain, and must follow these rules:

• It has 3–28 characters.
• It uses lowercase letters, digits and hyphens, with no hyphen at either end.
• It has at least one letter, and does not start with xn--.
• No other join address, and no coritan.gg name, already has it.
• It is not a reserved name.

The field changes what you type as you go. It turns capitals into lowercase letters, turns spaces, underscores and dots into hyphens, and drops every other character, so Survival SMP becomes survival-smp.

These names are reserved: account, accounts, admin, analytics, api, app, assets, auth, billing, bitbucket, blog, cdn, checkout, console, control, dashboard, database, db, demo, dev, development, dns, docs, documentation, email, files, ftp, gameproxy, git, github, gitlab, help, images, imap, img, internal, invoice, localhost, login, mail, media, metrics, mongo, mongodb, monitor, monitoring, mx, mysql, nameserver, news, ns and ns1 to ns8, oauth, panel, payment, payments, play, pop, portal, postgres, postgresql, private, proxy, public, rdp, redis, remote, root, sftp, shop, smtp, sql, ssh, sso, staging, static, stats, status, store, support, svn, test, testing, uploads, vpn, webmail, wiki and www.

The dashboard shows Join address survival-smp.coritan.gg created. and opens the join address's page. When you started from a server's Settings tab, its Network card shows the new Join address the next time you open it. Players join at survival-smp.coritan.gg. For a TCP service, they add the Edge port from the Overview tab after the name, such as survival-smp.coritan.gg:61234.

Subdomain is already in use

Another join address or a coritan.gg name has the name. Choose another, or select Suggest a name. The note beside the button reads That name is taken. until you do.

play is reserved; choose another.

The name is on the reserved list in Name rules. Choose another.

Use 3 to 28 characters.

The name is shorter than 3 or longer than 28 characters after the field has changed it.

Use lowercase letters, numbers and hyphens, with no hyphen at either end.

The name starts or ends with a hyphen. Remove it.

Include a letter; a subdomain cannot be only digits.

Add a letter to the name.

Punycode names are not accepted.

The name starts with xn--. Choose another.

A server hosted here is greyed out

The choice reads No servers on your account yet. Order a server first (Order a server), or connect a server you run elsewhere with A server elsewhere. A server someone shared with you does not count: ask its owner to create the join address.

A server elsewhere is greyed out for a TCP service

The choice reads TCP ports are available for servers hosted here only. A TCP service join address forwards only to a server hosted here.

Could not resolve upstream for service 1187

The server has no address yet, for example while Coritan is still setting it up. Wait until the server is running, then try again.

Another allocation took the edge listen port at the same time. Try again.

Two TCP service join addresses asked for the same edge port at once. Select Create join address again.

Every player is refused after you create the join address

PROXY protocol is on, and the server does not expect the header. Set the server to accept PROXY protocol version 2, or create another join address without it. For Paper, set proxies.proxy-protocol: true in config/paper-global.yml; for Velocity, set haproxy-protocol = true in velocity.toml.

• How join addresses work
• Customise the server list entry
• Use your own domain for a join address
• Connect a server you host elsewhere

Check a name with POST /api/v1/gameproxy/availability. It needs no token, changes the name as the dashboard's field does, and checks it against the rules and every name in use:

curl -X POST https://api.coritan.com/api/v1/gameproxy/availability \
  -H "Content-Type: application/json" \
  -d '{"subdomain": "survival-smp"}'

{"available": true, "subdomain": "survival-smp", "base_domain": "coritan.gg", "fqdn": "survival-smp.coritan.gg", "reason": null}

A name in use answers "available": false with the reason Subdomain is already in use. A name that breaks a rule answers with only available, subdomain and a reason, such as {"available": false, "subdomain": "play", "reason": "Subdomain 'play' is reserved"}. The subdomain you send must have 3–28 characters, or the call answers 422.

Ask for generated names with POST /api/v1/gameproxy/name-suggestions. It needs no token, and takes a count from 1 to 20, 5 by default:

curl -X POST https://api.coritan.com/api/v1/gameproxy/name-suggestions \
  -H "Content-Type: application/json" \
  -d '{"count": 3}'

{
  "suggestions": [
    {"display_name": "FrostHaven", "subdomain": "frosthaven482"},
    {"display_name": "PixelForge", "subdomain": "pixelforge157"},
    {"display_name": "CopperIsles", "subdomain": "copperisles903"}
  ],
  "base_domain": "coritan.gg"
}

A suggestion leaves out names that other join addresses hold, but can still match a coritan.gg name. Check it with the availability call before you create the join address.

Create the join address with POST /api/v1/gameproxy/routes:

curl -X POST https://api.coritan.com/api/v1/gameproxy/routes \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "survival-smp",
    "mode": "minecraft_java",
    "upstream_service_id": 1187,
    "display_name": "Survival SMP"
  }'

{
  "ok": true,
  "module_data": {
    "route_id": 42,
    "fqdn": "survival-smp.coritan.gg",
    "subdomain": "survival-smp",
    "base_domain": "coritan.gg",
    "mode": "minecraft_java",
    "listen_port": null,
    "upstream": "203.0.113.10:25565",
    "location_id": 3,
    "join_address": "survival-smp.coritan.gg",
    "ns_ready": true
  }
}

join_address is what players type, with the edge port after the name for a TCP service. route_id identifies the join address in the other join address calls. The call takes these fields:

The call also takes the server list fields, but does not save them. Set the server list entry afterwards (Customise the server list entry).

A name that another join address holds answers 400 with Subdomain 'survival-smp' is already in use on coritan.gg, and a name that breaks a rule answers 400 with the rule, such as Subdomain cannot be only digits. A body without upstream_service_id, or with upstream_host, answers 422 with Bind the join address to one of your servers with upstream_service_id. For a server hosted somewhere else, order an External Server. A server that is not yours, or that no longer exists, answers 404 with Server not found. A port the server does not have answers 422 and lists its ports, such as upstream_port must be one of this server's ports: 25565, 25580.