API Docs

This is the documentation for the Guilded Authlink API. You can read about what this website does here.

Before We Start

Authlink is compliant with RFC 6749. If you have any questions about how to design your client that aren't covered on this page, refer there!

Base URL

https://authlink.app/api/v1

Create an Application

Go to your applications page.
Click the "New Application" button.
Follow the instructions on that page to link your Guilded bot to an Authlink application.

Authorization

Each application has its own authorization URL to which it must send users in order to begin the OAuth flow. You can generate one of these with your desired scopes on your application's page.

The Basic Flow

User visits your application's website and clicks a "Log in with Guilded" button (or similar)
User is redirected to your authorization page on Guilded Authlink

If the user's browser session is not already verified, they will be taken through the start flow here

User allows or denies access to the scopes you selected
User is taken back to your redirect_uri with a code in the proceeding GET request's query string made by the user's browser
Your application exchanges code for an access token, which it can use to call API endpoints

This is the only flow type that Authlink offers support for.

Scopes

Name	Allows access to
identify	/users/@me
servers	/users/@me/servers & /servers/{server.id}
servers.members.read	/users/@me/servers/{server.id}/member

Authorization URL Structure

https://authlink.app/auth?client_id=5f61fed3-e4b4-4d3c-bfa8-29514b4d675c&scope=identify+servers&redirect_uri=https%3A%2F%2Fdemo.authlink.app%2Fme&prompt=consent&state=Um9yCthzQtjuIv6Cx48QS6NMXvdq2soQ

client_id - your application's client ID. This is the same as the linked bot ID that you created the application with.
scope - a list of url-encoded-space-separated scopes that you want to authorize your application for.
redirect_uri - the URI that your users should be redirected to after authorizing your application. This must be a valid entry under "Redirect URIs" on your application's page.
state - a unique, user-specific, unguessable string that Authlink should return to your application upon authorization. If it does not match what you sent, you should reject the authorization. Read more about this parameter.
prompt - If this is consent (default), reapproval will be prompted even if the user has already authorized your application with the selected scopes. If this is none, the authorization screen will be skipped automatically when these criteria are met.

Redirect URI

https://demo.authlink.app/me?code=M3oo84JqCYFcToYxjzWKVHEVnmd3Rfol&state=Um9yCthzQtjuIv6Cx48QS6NMXvdq2soQ

At this point, you should verify the state param mentioned above, if you included it. You can now exchange code for the user's access token:

Exchange Code

post/token

Exchange a code for an access token for use with the rest of the API or refresh an access token using a refresh token. Codes have a TTL of 15 seconds, so act fast! Refresh tokens do not expire, but they will be invalidated if the user deauthorizes your application.

Form Data Parameters (application/x-www-form-urlencoded)

Field	Type	Description
client_id	string	your applicaton's client id
client_secret	string	your application's client secret
grant_type	string	must be `authorization_code` or `refresh_token`
code?	string	the `code` query string argument passed through the redirect request. either this or `refresh_token` is required depending on `grant_type`
refresh_token?	string	the user's refresh token. either this or `code` is required depending on `grant_type`

Access Token Response

Property	Type	Description
access_token	string	the user's access token
token_type	string	always `Bearer`
expires_in	integer	seconds until `access_token` expires
refresh_token	string	the user's refresh token, which can be used to refresh the access token when it expires
scope	string	the scopes your application was authorized for, space-separated

And of course, if your application ever decides that it doesn't want the access token to be valid anymore:

Revoke Token

post/token/revoke

Revoke a token, immediately invalidating it and its associated access/refresh token depending on the type of token being revoked. See also: RFC 7009.

Form Data Parameters (application/x-www-form-urlencoded)

Field	Type	Description
client_id	string	your applicaton's client id
client_secret	string	your application's client secret
token	string	the token to revoke

Endpoints

Fly, my pretties! Now that you have your user's access token, you can begin making authorized requests with it. Make sure to include a proper authorization header:

Authorization: Bearer ACCESS_TOKEN

Get Current User

get/users/@me

Get the access token's representing user. Requires the identify scope.

JSON Response Example

{
    "id": "EdVMVKR4",
    "name": "shay",
    "subdomain": "shayy",
    "aliases": [
        {
            "alias": "shay",
            "discriminator": null,
            "name": "shay",
            "createdAt": "2021-03-03T20:59:27.797536+00:00",
            "userId": "EdVMVKR4",
            "gameId": 421074,
            "socialLinkSource": null,
            "additionalInfo": {},
            "editedAt": "2021-03-03T20:59:27.797536+00:00",
            "socialLinkHandle": null,
            "playerInfo": null
        }
    ],
    "avatar": "https://cdn.gilcdn.com/UserAvatar/c2da767cf9795e7c73facc399159fefc-Large.png?w=450&h=450",
    "banner": "https://cdn.gilcdn.com/UserBanner/acaa9d0f78dd8cdd93f3ce44d14c0260-Hero.png?w=1500&h=500",
    "createdAt": "2020-07-27T14:07:28.336Z",
    "userStatus": {
        "content": null,
        "customReactionId": 925765,
        "customReaction": {
            "id": 925765,
            "name": "blobspider",
            "png": "https://cdn.gilcdn.com/CustomReaction/b721e28333392c335fcff52eb27997fd-Full.webp?w=120&h=120",
            "webp": "https://cdn.gilcdn.com/CustomReaction/b721e28333392c335fcff52eb27997fd-Full.webp?w=120&h=120",
            "apng": null
        }
    },
    "moderationStatus": null,
    "aboutInfo": {
        "bio": "pfp: https://deviantart.com/zededge/art/Korra-Mass-Effect-FSRX-2-492156216",
        "tagLine": "computer user"
    },
    "lastOnline": "2022-04-19T17:02:55.499Z",
    "userPresenceStatus": 2,
    "userTransientStatus": null
}

Get Current User Servers

get/users/@me/servers

Get a list of partial servers for the access token's representing user. This will include private servers, which are indistinguishable from public servers. This endpoint cannot be paginated. Requires the servers scope.

JSON Response Example

[
    {
        "id": "wlVr3Ggl",
        "name": "Guilded",
        "subdomain": "Guilded-Official",
        "profilePicture": "https://cdn.gilcdn.com/TeamAvatar/f3ca3496e7f2b6bfaeddfbb6526bdec7-Large.png?w=450&h=450",
        "teamDashImage": "https://cdn.gilcdn.com/TeamBanner/e9a77c1048effb0d92d237bac30b563c-Hero.png?w=1500&h=500",
        "gameIds": [
            "350074",
            "216000",
            "10300",
            "104200",
            "10800",
            "10100"
        ],
        "memberCount": 22819
    },
    {
        "id": "4R5q39VR",
        "name": "Guilded-API",
        "subdomain": "guilded-api",
        "profilePicture": "https://cdn.gilcdn.com/TeamAvatar/a66e23924a4bc49fbf9242a98d955a7c-Large.png?w=450&h=450",
        "teamDashImage": "https://cdn.gilcdn.com/TeamBanner/62d94db23c910fa3a209b5edf2cf7387-Hero.png?w=1067&h=600",
        "memberCount": 1989
    },
    {
        "id": "QR46qKZE",
        "name": "Guilded API",
        "subdomain": "API-Official",
        "profilePicture": "https://cdn.gilcdn.com/TeamAvatar/04ff07e3a8f1f109c4885d25de8d913d-Large.png?w=450&h=450",
        "teamDashImage": "https://cdn.gilcdn.com/TeamBanner/cb593892c7c1446c1b4747b0c6743e0e-Hero.png?w=1864&h=445",
        "memberCount": 247
    },
    {
        "id": "NEaw5pGR",
        "name": "Blob Emojis",
        "subdomain": "blob-emoji",
        "profilePicture": "https://cdn.gilcdn.com/TeamAvatar/8bcde8550493d0c68468d15f408511cb-Large.png?w=450&h=450",
        "teamDashImage": "https://cdn.gilcdn.com/TeamBanner/f0cf92b4d0fbeb69221d47b202f2f2d8-Hero.png?w=1024&h=576",
        "memberCount": 27
    }
]

Some Guilded limitations are in effect here:

The memberCount property may be inaccurate by a considerable margin for larger servers.
Permissions and owner status could not be included in this response. If you need this information, use Get Current User Server Member.

Get Server

get/servers/{server.id}

Get a server that the access token's representing user is a member of. This is not available if the server is private. Requires the servers scope.

JSON Response

Field	Type	Description
id	string	The ID of the server.
name	string	The name of the server.
ownerId	string	The ID of the user that owns the server.
type?	string	The type of server as set in its settings page.
url	string	The URL slug of the server. There is a deprecated alternative to this property named `subdomain`.
timezone?	string	The server's timezone.
visibility	string	The server's visibility ("default" or "open-entry"). You should never receive a server with "private" visibility.
avatar	?string	The CDN URL of the server's avatar image. There is a deprecated alternative to this property named `profilePicture`.
banner	?string	The CDN URL of the server's banner image. There is a deprecated alternative to this property named `teamDashImage`.
isRecruiting?	boolean	Whether the server is accepting new member applications.
isVerified?	boolean	Whether the server is verified.
isDiscoverable?	boolean	Whether the server is discoverable. This is different from `visibility`.
followerCount?	integer	The number of followers that the server has.
memberCount	integer	The number of members that the server has. A value of `0` indicates that Authlink could not get the value from Guilded.
rolesById	object (string:Role)	The roles in the server.

Role Object

Field	Type	Description
id	integer	The ID of the role.
name	string	The name of the role.
color?	?integer	The role's primary color.
color2?	?integer	The role's secondary color, for gradient roles.
priority	integer	The priority of the role. Not to be confused with the displayed position of the role.
createdAt	string (ISO8601 timestamp)	When the role was created.
updatedAt?	?string (ISO8601 timestamp)	When the role was last updated.
isBase?	boolean	Whether the role is the server's base member role.
isMentionable?	boolean	Whether the role is mentionable by all members.
isSelfAssignable?	boolean	Whether the role is self-assignable without the Manage Roles permission.
isDisplayedSeparately?	boolean	Whether the role is displayed separately from other roles (or "hoisted").
serverId	string	The ID of the server that the role is in.
permissions	object (string:integer)	The role's permissions.
discordRoleId?	string (snowflake)	The ID of the Discord role that this role is synced to.
discordSyncedAt?	string (ISO8601 timestamp)	When this role was last synced to Discord.
bot?	object	Information about the bot that the role is for. Contains a `userId` key - the user ID of the bot.

JSON Response Example

{
    "id": "wlVr3Ggl",
    "name": "Guilded",
    "url": "Guilded-Official",
    "about": "The Official Guilded Team! For devs, friends, and fans alike!",
    "timezone": "America/Los Angeles (PST/PDT)",
    "type": "community",
    "visibility": "open-entry",
    "createdAt": "2018-10-05T19:25:13.449Z",
    "ownerId": "R403kZxA",
    "avatar": "https://cdn.gilcdn.com/TeamAvatar/f3ca3496e7f2b6bfaeddfbb6526bdec7-Large.png?w=450&h=450",
    "banner": "https://cdn.gilcdn.com/TeamBanner/fe3137f65c9f6d93658c8ed99b1a2ac8-Hero.png?w=1500&h=500",
    "socialInfo": {
        "twitch": "https://www.twitch.tv/teamguilded",
        "twitter": "@teamguilded",
        "youtube": "https://www.youtube.com/guildedgg",
        "facebook": "Guilded.gg"
    },
    "isRecruiting": true,
    "isVerified": true,
    "isDiscoverable": true,
    "followerCount": 1878,
    "gameIds": [
        350074,
        216000,
        10300,
        104200,
        10800,
        10100
    ],
    "flairs": [
        {
            "id": 3
        },
        {
            "id": 1,
            "amount": 323
        },
        {
            "id": 6
        }
    ],
    "memberCount": 24965,
    "rolesById": {
        "590401": {
            "id": 590401,
            "name": "Member",
            "color": 13750741,
            "permissions": {
                "chat": 35,
                "docs": 2,
                "forms": 16,
                "lists": 2,
                "media": 2,
                "voice": 4163,
                "forums": 67,
                "streams": 192,
                "calendar": 2,
                "announcements": 2
            },
            "priority": -11,
            "createdAt": "2018-10-05T19:25:16.216Z",
            "updatedAt": "2022-07-02T19:52:15.795Z",
            "isBase": true,
            "isMentionable": true,
            "isSelfAssignable": false,
            "isDisplayedSeparately": true,
            "serverId": "wlVr3Ggl"
        },
        "591232": {
            "id": 591232,
            "name": "Guilded Staff",
            "color": 10637544,
            "permissions": {
                "xp": 1,
                "bots": 1,
                "chat": 503,
                "docs": 15,
                "forms": 18,
                "lists": 63,
                "media": 15,
                "voice": 8179,
                "forums": 123,
                "general": 64564,
                "streams": 243,
                "brackets": 3,
                "calendar": 31,
                "scheduling": 11,
                "matchmaking": 20,
                "recruitment": 55,
                "announcements": 7,
                "customization": 49
            },
            "priority": 17,
            "color2": 3188367,
            "createdAt": "2018-10-05T21:27:27.522Z",
            "updatedAt": "2022-07-02T00:14:29.845Z",
            "discordRoleId": "497837817569869824",
            "discordSyncedAt": "2018-10-05T22:50:38.864Z",
            "isMentionable": false,
            "isSelfAssignable": false,
            "isDisplayedSeparately": true,
            "serverId": "wlVr3Ggl"
        },
        "25746098": {
            "id": 25746098,
            "name": "Bot",
            "color": 8296183,
            "permissions": {
                "xp": 1,
                "bots": 1,
                "chat": 503,
                "docs": 15,
                "forms": 18,
                "lists": 63,
                "media": 15,
                "voice": 8179,
                "forums": 123,
                "general": 130100,
                "streams": 243,
                "brackets": 3,
                "calendar": 31,
                "scheduling": 11,
                "matchmaking": 20,
                "recruitment": 55,
                "announcements": 7,
                "customization": 49
            },
            "priority": 18,
            "color2": 6654968,
            "createdAt": "2021-11-30T23:41:42.940Z",
            "updatedAt": "2022-07-02T00:14:29.845Z",
            "isMentionable": false,
            "isSelfAssignable": false,
            "isDisplayedSeparately": false,
            "serverId": "wlVr3Ggl"
        }
    }
}

Get Current User Server Member

get/users/@me/servers/{server.id}/member

Get the access token's representing user's member object for a specific server. This is not available if the server is private. Requires the servers.members.read scope and, for an inner user object to be included, the identify scope.

Query Parameters

Parameter	Description	Required	Default
getPermissions	Whether to return the member's calculated permissions at a server level (slower)	no	false

JSON Response

Field	Type	Description
user?	object (user)	The member's inner user. Will contain `id` and `name` at minimum. Only present if you have the `identify` scope.
teamXp?	integer	The member's XP in this server. Only present if `getPermissions` was false.
membershipRole?	string	A generic string denoting the member's "role" in this server based on their permissions. This is unrelated to any roles they have.
joinedAt	?string (ISO8601 timestamp)	When the member joined this server. Only present if `getPermissions` was false.
roleIds?	integer[]	The member's role IDs in this server. Only present if `getPermissions` was true.
nickname?	string	The member's nickname in this server. Only present if `getPermissions` was true and if the member has a nickname set.
isOwner?	boolean	Whether the member owns this server. Only present if `getPermissions` was true.
permissions?	object (string:integer)	The member's calculated permissions in this server. Only present if `getPermissions` was true.

JSON Response Example

This example provides the getPermissions query parameter as false (or not present). For more details on what this parameter changes, see the above table.

{
    "user": {
        "id": "EdVMVKR4",
        "name": "shay",
        "avatar": "https://cdn.gilcdn.com/UserAvatar/c2da767cf9795e7c73facc399159fefc-Large.png?w=450&h=450",
        "userStatus": {
            "content": null,
            "customReactionId": 925765,
            "customReaction": {
                "id": 925765,
                "name": "blobspider",
                "png": "https://cdn.gilcdn.com/CustomReaction/b721e28333392c335fcff52eb27997fd-Full.webp?w=120&h=120",
                "webp": "https://cdn.gilcdn.com/CustomReaction/b721e28333392c335fcff52eb27997fd-Full.webp?w=120&h=120",
                "apng": null
            }
        },
        "stonks": 56,
        "lastOnline": "2022-04-19T17:02:55.499Z"
    },
    "teamXp": 1551,
    "membershipRole": "admin",
    "joinedAt": "2021-08-02T16:59:54.724Z"
}

Inversely to the above, the following example provides the getPermissions query parameter as true:

{
    "user": {
        "id": "EdVMVKR4",
        "name": "shay",
        "userPresenceStatus": 2,
        "avatar": "https://cdn.gilcdn.com/UserAvatar/c2da767cf9795e7c73facc399159fefc-Large.png?w=450&h=450",
        "banner": "https://cdn.gilcdn.com/UserBanner/acaa9d0f78dd8cdd93f3ce44d14c0260-Hero.png?w=1500&h=500"
    },
    "membershipRole": "admin",
    "nickname": "this shay",
    "roleIds": [
        24821967
    ],
    "isOwner": true,
    "permissions": {
        "chat": 499,
        "docs": 3,
        "forms": 16,
        "lists": 3,
        "media": 3,
        "voice": 6211,
        "forums": 67,
        "general": 8192,
        "streams": 51,
        "calendar": 3,
        "scheduling": 3,
        "announcements": 2,
        "customization": 16
    }
}

Menu

API Docs

Before We Start

Base URL

Create an Application

Authorization

The Basic Flow

Scopes

Authorization URL Structure

Redirect URI

Exchange Code

Access Token Response

Revoke Token

Endpoints

Get Current User

JSON Response Example

Get Current User Servers

JSON Response Example

Get Server

JSON Response

Role Object

JSON Response Example

Get Current User Server Member

Query Parameters

JSON Response

JSON Response Example