← All NIPs

NIP-98

HTTP Auth

DraftHTTP

Log in to an HTTP API with your nostr key: sign a short-lived kind 27235 event naming the exact URL and method, and send it in the Authorization header.

Status
In use and still allowed to change.
Kinds
Tags
  • method
  • payload
  • u
Last changed
Dec 8, 2023

Try it

Edit the form or the JSON: both stay in sync, the badge says whether the result is valid, and tapping any field explains it.

What to build

How the parts connect: Sign, then send

Examples
Valid

Form
GET

Any HTTP request carrying a NIP-98 Authorization header.

Headers

The string "Nostr " plus the base64-encoded signed event.

The auth event inside the header

{
  "kind": 27235,
  "created_at": 1735689600,
  "tags": [
    [
      "u",
      "https://api.alpha.example/v1/notes?limit=10"
    ],
    [
      "method",
      "GET"
    ]
  ],
  "content": "",
  "pubkey": "e550c6e92808f358382b7b8c14345344f5ef9a299529834d1c26d57b6ace44cc",
  "id": "2ddb1906131aa6464e5eeb99756398fc557574e437978ce6c6324ca69641a8d3",
  "sig": "3b1505547b356326eff191f56fd44d46f6c0aeda7d0ffa25909a08506c38462d5a75b062ffd1252ebf16fb9c7d36cdd65b351d0675a2fe306235e9471e5974d0"
}

Body application/json

The request body, here JSON (any body works). Its SHA-256 goes in the auth event's payload tag.

Responses

  • 200 Authorized; the server handles the request.
  • 401 Missing, expired or mismatching auth event.

How this NIP works

Step 1 of 5

Describe the request

Create a kind 27235 event with a u tag (the full URL, query included) and a method tag (GET, POST…). Content stays empty.

In the course

No course chapter covers this NIP yet. The editor above is the quickest way in.

Builds on

Used by

See also

Specification

Specification text is quoted in English from the nostr-protocol/nips repository. Our explanations and the interface are translated. Source on GitHub at commit 0046368

Read the spec269 words, quoted from the repository at commit 0046368.

This NIP defines an ephemeral event used to authorize requests to HTTP servers using nostr events.

This is useful for HTTP services which are built for Nostr and deal with Nostr user accounts.

Nostr event

A kind 27235 (In reference to RFC 7235) event is used.

The content SHOULD be empty.

The following tags MUST be included.

  • u - absolute URL
  • method - HTTP Request Method

Example event:

{
  "id": "fe964e758903360f28d8424d092da8494ed207cba823110be3a57dfe4b578734",
  "pubkey": "63fe6318dc58583cfe16810f86dd09e18bfd76aabc24a0081ce2856f330504ed",
  "content": "",
  "kind": 27235,
  "created_at": 1682327852,
  "tags": [
    ["u", "https://api.snort.social/api/v1/n5sp/list"],
    ["method", "GET"]
  ],
  "sig": "5ed9d8ec958bc854f997bdc24ac337d005af372324747efe4a00e24f4c30437ff4dd8308684bed467d9d6be3e5a517bb43b1732cc7d33949a3aaf86705c22184"
}

Servers MUST perform the following checks in order to validate the event:

  1. The kind MUST be 27235.
  2. The created_at timestamp MUST be within a reasonable time window (suggestion 60 seconds).
  3. The u tag MUST be exactly the same as the absolute request URL (including query parameters).
  4. The method tag MUST be the same HTTP method used for the requested resource.

When the request contains a body (as in POST/PUT/PATCH methods) clients SHOULD include a SHA256 hash of the request body in a payload tag as hex (["payload", "<sha256-hex>"]), servers MAY check this to validate that the requested payload is authorized.

If one of the checks was to fail the server SHOULD respond with a 401 Unauthorized response code.

Servers MAY perform additional implementation-specific validation checks.

Request Flow

Using the Authorization HTTP header, the kind 27235 event MUST be base64 encoded and use the Authorization scheme Nostr

Example HTTP Authorization header:

Authorization: Nostr 
eyJpZCI6ImZlOTY0ZTc1ODkwMzM2MGYyOGQ4NDI0ZDA5MmRhODQ5NGVkMjA3Y2JhODIzMTEwYmUzYTU3ZGZlNGI1Nzg3MzQiLCJwdWJrZXkiOiI2M2ZlNjMxOGRjNTg1ODNjZmUxNjgxMGY4NmRkMDllMThiZmQ3NmFhYmMyNGEwMDgxY2UyODU2ZjMzMDUwNGVkIiwiY29udGVudCI6IiIsImtpbmQiOjI3MjM1LCJjcmVhdGVkX2F0IjoxNjgyMzI3ODUyLCJ0YWdzIjpbWyJ1IiwiaHR0cHM6Ly9hcGkuc25vcnQuc29jaWFsL2FwaS92MS9uNXNwL2xpc3QiXSxbIm1ldGhvZCIsIkdFVCJdXSwic2lnIjoiNWVkOWQ4ZWM5NThiYzg1NGY5OTdiZGMyNGFjMzM3ZDAwNWFmMzcyMzI0NzQ3ZWZlNGEwMGUyNGY0YzMwNDM3ZmY0ZGQ4MzA4Njg0YmVkNDY3ZDlkNmJlM2U1YTUxN2JiNDNiMTczMmNjN2QzMzk0OWEzYWFmODY3MDVjMjIxODQifQ

Reference Implementations