Skip to content
go-api-boilerplate

Mail a sign-in link.

POST
/v1/login-links
curl --request POST \
  --url https://example.com/api/user/v1/login-links \
  --header 'Content-Type: application/json' \
  --data '{ "email": "hello@example.com", "next": "example", "state": "example" }'

Mails a one-time link, valid for 15 minutes, to the address. The answer is the same whether or not an account has the address: redeeming the link with the auth service registers one. Limited per client IP and per address.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
email
required
string format: email
<= 254 characters
next

A path on the web app to go to after signing in, such as /consent?request=42. Anything else is dropped.

string
<= 2048 characters
state

A random value the browser keeps and the link carries back as state, so that browser can tell the link is its own and use it at once. The web app asks before using any other link, which may be someone else’s (login CSRF). Anything that doesn’t match is dropped.

string
<= 64 characters /^[A-Za-z0-9_-]*$/

Example generated

{
  "email": "hello@example.com",
  "next": "example",
  "state": "example"
}

Responses

Section titled “Responses”

202

Section titled “202”

Accepted; the mail goes out shortly.

Media typeapplication/json

Nothing to report; the mail is on its way.

object

Example generated

{}

400

Section titled “400”

The request is malformed.

Media typeapplication/problem+json

An RFC 9457 problem.

object
type
required
string
title
required
string
status
required
integer
detail

Written for the user.

string
instance
string
request_id
string
errors

What is wrong with each field of the request.

object
key
additional properties
string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "errors": {
    "additionalProperty": "example"
  }
}

403

Section titled “403”

The token isn’t a user’s, lacks the scope, or the request came from another origin.

Media typeapplication/problem+json

An RFC 9457 problem.

object
type
required
string
title
required
string
status
required
integer
detail

Written for the user.

string
instance
string
request_id
string
errors

What is wrong with each field of the request.

object
key
additional properties
string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "errors": {
    "additionalProperty": "example"
  }
}

413

Section titled “413”

The body is larger than 4 KiB.

Media typeapplication/problem+json

An RFC 9457 problem.

object
type
required
string
title
required
string
status
required
integer
detail

Written for the user.

string
instance
string
request_id
string
errors

What is wrong with each field of the request.

object
key
additional properties
string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "errors": {
    "additionalProperty": "example"
  }
}

429

Section titled “429”

Too many links asked for, from this client or for this address.

Media typeapplication/problem+json

An RFC 9457 problem.

object
type
required
string
title
required
string
status
required
integer
detail

Written for the user.

string
instance
string
request_id
string
errors

What is wrong with each field of the request.

object
key
additional properties
string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "errors": {
    "additionalProperty": "example"
  }
}

Headers

Section titled “Headers”
Retry-After
required
string
/^[1-9][0-9]*$/

Seconds until a request may succeed.

500

Section titled “500”

Something failed on the server; the request ID leads to the log line.

Media typeapplication/problem+json

An RFC 9457 problem.

object
type
required
string
title
required
string
status
required
integer
detail

Written for the user.

string
instance
string
request_id
string
errors

What is wrong with each field of the request.

object
key
additional properties
string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "request_id": "example",
  "errors": {
    "additionalProperty": "example"
  }
}