Skip to main content

Authentication

To access our API endpoints, your app needs to authenticate against our API with every request. Let's have a look at authenticating HTTP requests and WebSocket connections.

Authenticating HTTP requests

Authenticating an HTTP request is very simple. As you only have one API token for your whole app, it's sufficient to add it as a header to each request:

Y-Api-Token: 157f078e-a20a-49ed-abd5-a92cc366de85

Exceptional responses

Yunite will send back the corresponding HTTP status codes in case of authentication, authorization, or other failures. These codes are general, and there might be more codes or different code meanings depending on which particular endpoint you're calling.

CodeDescription
400Bad request. It happens if you don't provide a guild ID if required or otherwise send a malformed request.
401Unauthorized. It may happen if you fail to provide an existing, valid token.
402The requested guild does not have an active Premium subscription.
403Returned if you're attempting to access a resource your token is not authorized for.
404Route not found.
429You violated our ratelimits. Repeated violation may result in a ban of your application.

Statuscodes >= 500 may happen from time to time as well but are rare. Those indicate an internal error in our systems. If you encounter them frequently, please let us know how to reproduce that issue so we can combat it.

Authenticating WebSockets

WebSockets' authentication is performed using a one-time token that gets passed as a query parameter due to undefined behavior related to the submission of headers during the handshake with some WebSocket client libraries.

  1. Use this endpoint to retrieve a one-time token to connect to a WebSocket. Remember to pass your main API token as a header, just as with any other HTTPS endpoint in the API.
GET
Get one time token
https://yunite.xyz/api/v3/websocket-tokenResponse
{
    "type": "string",
    "value": "the one time token"
}

  1. Connect to the target WebSocket and add this query parameter (example):

    ?token=157f078e-a20a-49ed-abd5-a92cc366de85

After that, the WebSocket should connect and authenticate successfully.

caution

These tokens are only used for connecting to the target WebSocket immediately. They will expire after five seconds.