Blog Adding "login with urbit" capability to an external website

Jeremy Tunnell at

One major beneficial feature of Urbit is that it has identity baked into the whole system.

You can purchase an Urbit ID (called a planet), and nobody can take it from you. It's yours, forever, and it can become a way to prove you are who you say you are online.

Up until now, Urbit IDs are used to log into the Urbit operating system. However, recently a company called DCSpark wrote an app (a gall agent, technically), which enables external websites to use Urbit as a login provider.

Here's how it works:

  1. An Urbit instance installs the DCSpark gall app. This app runs in the background and generates a password that can be used to send a ship name to it to process.
  2. An external website sends a request to the Urbit instance containing the password and the ship name.
  3. The Urbit instance sends a private message to the Urbit ship with a login key, and returns that login key to the external website.
  4. The external website then asks the user to check their messages and input the key to verify their identity.

So, here's what you do to get it working on PHP using CURL:

  1. Install the DCSpark urbit-auth gall app using the instructions here.
  2. Get your auth key with: :auth-id %print-key
  3. Find your endpoint. Your endpoint is where you log onto your urbit (Highly, highly recommended to use SSL) Example: If you login at then your endpoint will be
  4. Create a web form that accepts an urbit id name (example: ~watsup-sognem)
  5. Have that form submit a POST request to another php page which has the code below (see: request code)
  6. Listen for the key that is returned and store that on your the database or something.
  7. Redirect the user to a page asking them for their login code.
  8. Check the login code to make sure it's correct and then log the user in.

Request code:

$urbit_ship = $_POST['urbit_ship'];  //Urbit ship name
$url = ""; //Your endpoint
$urbit_auth = 'ilsjef.asdifj.fjiasl.fjisdl';  //What you got when you got the key on the gall app
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $urbit_ship);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'accept: application/json',
	'content-type: application/json',
    'auth: '.$urbit_auth
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$result = json_decode(curl_exec($ch));
$httpcode = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

if($httpcode != 200){
	echo 'Sorry, there was a problem connecting with the urbit server.';
else if($result->error){
	echo 'Sorry, there was a problem: '.$result->error;
	$token = $result->token;
	$target = $result->target;
	//Store the token in your database to check later

Add Comment