CTFAuth Developers Guide

This guide will walk you through how to integrate CTFAuth into your site. A backend server is required for this API.

Here is a Node.js Project that demonstrates the API: https://github.com/ParretLabs/ctfauth_example
The live app itself as well: parretlabs.xyz:8015/

Current Version: v2

Obtaining an API Key

The only way to obtain an API Key is through manual means.

Contact Electro for an API Key:
Reddit: /u/-Electron-
Discord: @Electro#1010

Just ask me for an API Key and give me a simple reason of what you’re going to use it for.

One API Key per project.

Abstract API Flow

Here’s the basic flow of how the API works in 5 steps:

1. Your server generates a verification link by calling an API endpoint. Your server is given:
   • A verification URL to give to the client
   • A verification token that tracks the client while they follow the verification procedures. Useful if the user inputted some information on your site. You can map their information to their verification token, then use it after they’ve verified themselves.
   • Note: Do not spam this endpoint, it is rate limited at 120 links per 20 minutes.
2. When the client reaches the verification page, they will be asked to input their Profile ID then change their flair to verify they own the profile.
3. After they are done verifying their ownership, a JSON POST request will be sent to a callback endpoint on your server. The payload contains:
   • A verified boolean property, that signifies if the user has been verified.
   • The verified profile ID of the user.
   • The verification token of the user.
   • Your API's secret. (Used to verify that the request is legitimate.)
   • Note: Your callback URL must be on a hosted domain and cannot be localhost. Consider using a tunneling service like ngrok to make development easier.
4. Your server’s callback endpoint will send back a JSON object with a redirect URL stored within.
5. The API receives that redirect URL and sends the user there.

CTFAuth handles profile verification and stores a 24-hour login token cookie after a player logs in. This token will allow the player to verify their profile simply by clicking a single button labeled "One Touch Login". This button will appear while the players login token is still valid.

Settings

You can access the settings panel of your API Key at https://ctfauth.herokuapp.com/settings

There you can change the Brand Name, Brand Image URL, Home Page URL, and Callback URL.

Endpoints

The current API Endpoint Base URL is: https://ctfauth.herokuapp.com/api/v2

All endpoints use the header Content-Type: application/json. Your callback URL should also accept this content type as well.

API Key is passed through the Authentication HTTP header. Example:
"Authorization": "Basic __API_KEY__"
Replace the __API_KEY__ with your actual API Key.

---

POST /generate_verification_link
This endpoint generates a verification link to send to your users. Should NOT be used client side. Does not require a JSON payload to be sent.

Returns:

{
	url: {String} The URL you can give the user.
	verificationToken: {String} The verification token you can use to track the user.
}

Callback Server

Your callback endpoint should accept Content-Type: application/json.

Your endpoint will receive a POST request with this JSON payload:

{
	verified: {Boolean} Shows whether the profile was verified or not.
	profileID: {String} The verified profile ID of the user.
	verificationToken: {String} The verification token of the user.
	apiSecret: {String} Your API secret. Use it to verify that the request is legitimate.
}

After your endpoint as processed the payload (e.g. creating an account), it should return a JSON payload containing a redirect URL:

{
	redirectURL: {String} The URL to redirect the user too.
}

And that’s the end of the authentication flow.