Connect git, phone apps and other tools

Scripts, git, phone sync apps and MCP clients cannot sign in through a browser. They use the application’s API keys instead. This guide shows how each kind of client sends a key.

You need:

• an access (or a route) whose auth modes include api-key — see Protect with API keys;
• a key, from edgible application api-keys create --app <app-id> --name <who-uses-it>.

An application can have up to 3 keys. Give each client its own key so you can delete one without breaking the others.

Three ways to send a key

How	Example	Typical clients
Bearer token	Authorization: Bearer sk_…	curl, scripts, SDKs, MCP clients
X-API-Key header	X-API-Key: sk_…	tools that already use this header
Basic auth	any username, the key as the password	git, calendar and contact sync apps, WebDAV

For Basic auth you can also put the key in the username and leave the password empty — that is what a URL such as https://sk_…@files.example.com/ sends.

When a request has no key or a wrong one, the edge answers 401 with WWW-Authenticate: Basic realm="edgible". That header is what makes git and sync apps ask for (or send) their saved username and password, so Basic-auth clients work without extra setup.

Requires agent 1.4.14 or later on the serving device.

curl

curl -H "Authorization: Bearer sk_…" https://api.example.com/v1/things
curl -H "X-API-Key: sk_…" https://api.example.com/v1/things
curl -u "me:sk_…" https://api.example.com/v1/things

git

Clone over HTTPS. git asks for a username and password: enter any username and the key as the password.

$ git clone https://git.example.com/team/repo.git
Username for 'https://git.example.com': me
Password for 'https://me@git.example.com': sk_…

To avoid typing the key each time, let a git credential helper remember it (for example git config --global credential.helper store, or your system keychain helper). Avoid putting the key in the clone URL: git saves the URL, key included, in .git/config.

Calendar and contact apps (CalDAV / CardDAV)

In the app’s account settings (for example DAVx⁵ on Android, or Settings → Calendar → Accounts → Add Account → Other on iPhone):

• Server: https://cal.example.com/ (your application’s hostname)
• Username: anything, for example your name
• Password: the API key

MCP servers you host on Edgible

To give an assistant your Edgible applications and devices, you need no key: connect it to Edgible’s hosted MCP server, which signs you in with OAuth. See Use Edgible with an AI assistant. This section is about an MCP server of your own that runs as an Edgible application.

Your MCP server is reached over HTTPS like any other app. Clients that let you set request headers can send the key as a Bearer token. The configuration field names differ between clients; a typical entry looks like this:

{
  "mcpServers": {
    "my-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer sk_…" }
    }
  }
}

Clients that only offer an OAuth “sign in” button, with no way to set a header, cannot connect to your own server yet. Browser-based clients also need CORS: see Calling from a browser. In managed CORS mode the edge lets browser code read the WWW-Authenticate header.

Apps that also use Edgible login

A route that allows both edgible-login and api-key sends a request with no credentials to the Edgible login page. Browsers follow that; git, sync apps and MCP clients do not, so they fail before they ever send the key. Give machine clients their own path that allows only api-key:

access:
  - name: web
    type: https
    target: { workload: app, port: http }
    policies:
      auth: { modes: [edgible-login] }
    routes:
      - path: /dav/*
        target: { workload: app, port: http }
        policies: { auth: { modes: [api-key] } }
      - path: /*
        target: { workload: app, port: http }

People use the site with Edgible login; the sync app points at https://<host>/dav/ with the key as its password. Routes without their own policies use the access-level ones. See Path routes.

Apps with their own accounts

On an api-key route the edge checks the key and then passes the request, including the Authorization header, to your application. An application that runs its own Basic-auth login (for example Gitea, Nextcloud or Radicale with authentication turned on) will try to sign in with the key and fail. Either configure the app to trust the edge (turn off its own login on that path), or skip the edge check on that path with app-native and use the app’s own accounts — see Authentication modes.

How checks and revocation work

• The serving device checks a key with the platform, then remembers a successful check for up to 5 minutes (never past the key’s expiry). Busy clients therefore do not wait for the platform on every request. A rejected key is never remembered.
• If the platform cannot be reached after that, requests with the key get 401 until it can be reached again.
• Deleting a key (edgible application api-keys delete --app <app-id> --key-id <id>) tells the serving devices to forget it straight away; a device that misses the message stops accepting the key within 5 minutes.
• Removing api-key from a route takes effect on the next request, even for remembered keys.

Keys belong to the application, not to a person. Per-person tokens and OAuth sign-in for applications you host are not available yet. (Edgible’s own hosted MCP server already signs people in with OAuth; see Use Edgible with an AI assistant.)