> For the complete documentation index, see [llms.txt](https://docs.earthbuild.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.earthbuild.dev/docs/misc/public-key-auth.md).

# Public key authentication

{% hint style="danger" %}
**Decommissioned with Earthly Cloud**

Public-key authentication was a feature of the hosted Earthly Cloud account service. Along with other Earthly Cloud features, hosted accounts and the central authentication server were decommissioned. EarthBuild is a self-hosted build tool with no concept of accounts, organizations, or a hosted authentication server. See [Migrating from Earthly](https://docs.earthbuild.dev/migrating-from-earthly.md) for details.
{% endhint %}

## Historical Overview

Earthly originally provided public-key based authentication for its hosted service. This page details how that authentication mechanism operated historically.

### What is public-key authentication

Public key authentication provides greater security compared to password authentication; it is achieved by using [asymmetric cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography).

A user generates a pair of private and public keys; the public key is publicly distributed to anyone who wishes to send an encrypted message that only the holder of the private key can decrypt. It is important that you **never share your private key**, otherwise anyone could use it to access data that is only intended for you.

Similarly, it is possible to sign data using your private key -- any user who has your public key can use it to verify the message was signed by you (or anyone who has access to your private key).

For these reasons, it is crucial that your private key remains private -- as a result, Earthly never stored or transmitted your private key.

### How did Earthly implement public-key authentication

Earthly accounts could be associated with any number of public keys (both `ssh-rsa`, and `ssh-ed25519` public keys were supported). These public keys were stored on the Earthly server, in a database that mimics the `~/.ssh/authorized_keys` file one typically finds on a server.

The client first connected to the Earthly server over an HTTPS connection; the client responded with a [cryptographically-secure random](https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator) blob of data. The client then passed that blob of data to the [ssh-agent](https://en.wikipedia.org/wiki/Ssh-agent) process running on the local host via `SSH_AUTH_SOCK`. The ssh-agent signed the blob of data, and returned the signature -- the client never read private keys directly.

This signature was sent to the Earthly server; if the signature was verified using a registered public key, then the server responded with a [JSON Web Token (JWT)](https://en.wikipedia.org/wiki/JSON_Web_Token) used for the session duration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.earthbuild.dev/docs/misc/public-key-auth.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
