API reference

Invitations

For your server, with the secret key: check whether someone is invited, and redeem the code.

Ask whether an address is invited (address in the URL)

GET/api/v1/invitedSecret key

The older form of the question above, kept for existing callers. The address travels in the URL and can end up in access logs: prefer POST.

curl "$NEARLYIN_URL/api/v1/invited?email=ada@example.com" \
  -H "Authorization: Bearer $NEARLYIN_SECRET_KEY"

Parameters

emailquery · string · required: The address to check. Case and surrounding spaces do not matter.

Responses

200 Whether the address was invited to this product.

{
  "invited": true
}

400 invalid_email: This is not a valid email address.

401 unauthorized: Missing, unknown or revoked key.

429 rate_limited: Too many requests. Retry after the number of seconds in Retry-After.

Ask whether an address is invited

POST/api/v1/invitedSecret key

For your sign-up: let someone in only if this says true. Unknown addresses are simply not invited. The address travels in the body, so it stays out of access logs.

curl "$NEARLYIN_URL/api/v1/invited?email=ada@example.com" \
  -H "Authorization: Bearer $NEARLYIN_SECRET_KEY"

Body

emailstring · required: The address to check. Case and surrounding spaces do not matter.

Responses

200 Whether the address was invited to this product.

{
  "invited": true
}

400 invalid_email: This is not a valid email address.

401 unauthorized: Missing, unknown or revoked key.

429 rate_limited: Too many requests. Retry after the number of seconds in Retry-After.

Check an invitation code

POST/api/v1/invites/verifySecret key

The invitation mail links to your product with ?invite=<code>. A valid code proves two things: the person is invited, and the address is theirs, because the link was only ever sent there. Checking does not use the code up, so it is safe when the page opens (mail scanners open links too). Codes work for 30 days.

curl -X POST $NEARLYIN_URL/api/v1/invites/verify \
  -H "Authorization: Bearer $NEARLYIN_SECRET_KEY" -H 'Content-Type: application/json' \
  -d '{"token":"<code from the link>"}'

Body

tokenstring · required: The value of the invite query parameter your product received.

Responses

200 valid: false for a code that is unknown, expired, already redeemed or from another product, without saying which.

{
  "valid": true,
  "email": "ada@example.com"
}

400 invalid_request: The request could not be read or is missing a required field.

401 unauthorized: Missing, unknown or revoked key.

429 rate_limited: Too many requests. Retry after the number of seconds in Retry-After.

Use an invitation code up

POST/api/v1/invites/redeemSecret key

Like verify, but works exactly once. Call it at the moment you create the account, and create the account only if it answers valid: true. The entry is redeemed afterwards and the event entry.redeemed goes out; the person stays invited.

If your request got no answer (a timeout, a crash before the account existed), the code may be spent all the same. Send an Idempotency-Key to make redeeming safe to repeat: with the same key and the same code, a repeat within 24 hours gets the first answer again, marked with the response header Idempotent-Replayed: true.

curl -X POST $NEARLYIN_URL/api/v1/invites/redeem \
  -H "Authorization: Bearer $NEARLYIN_SECRET_KEY" -H 'Content-Type: application/json' \
  -d '{"token":"<code from the link>"}'

Parameters

Idempotency-Keyheader · string · optional: 1 to 255 visible ASCII characters, unique per sign-up you are completing. Keep it for the retries of that sign-up.

Body

tokenstring · required: The value of the invite query parameter your product received.

Responses

200 valid: true exactly once per code.

{
  "valid": true,
  "email": "ada@example.com"
}

400 invalid_request: The request could not be read or is missing a required field. / invalid_idempotency_key: The Idempotency-Key must be 1 to 255 visible ASCII characters.

401 unauthorized: Missing, unknown or revoked key.

409 idempotency_in_progress: A request with this Idempotency-Key is still running.

422 idempotency_key_reused: This Idempotency-Key was already used for a different request.

429 rate_limited: Too many requests. Retry after the number of seconds in Retry-After.