Initiate authentication via magic link

POST

/auth

const url = 'https://api-dev.mindflow.io/v1/auth';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"email":"hello@example.com","name":"example","tenant":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api-dev.mindflow.io/v1/auth \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "hello@example.com", "name": "example", "tenant": "example" }'

Providing an email and name will create a new user if they don’t exist. It will then initiate a custom authentication challenge using a magic link mechanism via Cognito.

Curl Example

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "alice@example.com", "name": "Alice Smith"}' \
  "https://api.example.com/v1/auth"

Flow

The frontend or third-party backend sends a request with the user email and name.
Mindflow:
- Checks if the user exists in Cognito
- Creates the user if missing
- Sets a random password for the user
- Triggers the InitiateAuth flow to retrieve a session
- Creates a magic link for the user to complete authentication
- Returns the magic link URL
This URL can later be used to complete authentication.

Security

This endpoint will only be deployed to specific accounts
This endpoint will have its own API key

Response

A 200 response returns a JSON payload with the magic link URL.
A 500 is returned if the flow fails (user creation, Cognito errors, etc.).

Authorizations

bearerAuth

Request Body^required

application/json

object

email

required

Email of the user requesting SSO via magic link.

string format: email

<= 254 characters

name

required

Name of the user requesting SSO via magic link.

string

<= 128 characters

tenant

required

Tenant of the user requesting SSO via magic link.

string

<= 64 characters

Example^generated

{
  "email": "hello@example.com",
  "name": "example",
  "tenant": "example"
}

Responses

200

Successfully initiated magic link authentication.

application/json

object

magicLink

required

Direct URL to complete authentication.

string format: uri

<= 2048 characters

Example^generated

{
  "magicLink": "https://example.com"
}

Headers

X-RateLimit-Limit

integer format: int32

>= 1 <= 1000

The maximum number of requests per time window.

X-RateLimit-Remaining

integer format: int32

<= 1000

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset

string format: date-time

<= 29 characters

The time at which the current rate limit window resets.

Retry-After

integer format: int32

>= 1 <= 3600

The number of seconds to wait before retrying the request after receiving a 429 response.

Access-Control-Allow-Origin

string

Allowed values: *

Specifies the allowed origins for CORS.

400

The request was invalid. Common causes include:

Invalid timestamp format.
Using cursor with before or after.
Missing limit when using before or after.
Invalid field names in the fields parameter.

See the error response for specific details about what went wrong.

application/json

object

type

URI reference identifying the problem type. When absent, “about:blank” per RFC 9457 Section 3.1.1.

string format: uri-reference

default: about:blank <= 2048 characters

title

required

Short, human-readable summary of the problem type (RFC 9457 Section 3.1.3).

string

<= 256 characters /^[^\p{C}]+$/

status

required

HTTP status code for this occurrence (advisory; same as response status) (RFC 9457 Section 3.1.2).

integer format: int32

>= 100 <= 599

detail

Human-readable explanation specific to this occurrence (RFC 9457 Section 3.1.4).

string

<= 500 characters

instance

URI reference identifying the specific occurrence (RFC 9457 Section 3.1.5).

string format: uri-reference

<= 2048 characters

code

Machine-readable error code for bad request / validation failure.

string

Allowed values: BAD_REQUEST

Example

{
  "type": "about:blank",
  "code": "BAD_REQUEST"
}

Headers

X-RateLimit-Limit

integer format: int32

>= 1 <= 1000

The maximum number of requests per time window.

X-RateLimit-Remaining

integer format: int32

<= 1000

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset

string format: date-time

<= 29 characters

The time at which the current rate limit window resets.

Retry-After

integer format: int32

>= 1 <= 3600

The number of seconds to wait before retrying the request after receiving a 429 response.

Access-Control-Allow-Origin

string

Allowed values: *

Specifies the allowed origins for CORS.

401

Authentication failed. The request lacks valid credentials or the provided credentials are invalid.

Ensure you have:

A valid API key or token.
Proper authentication headers.
Required permissions.

application/json

object

type

URI reference identifying the problem type. When absent, “about:blank” per RFC 9457 Section 3.1.1.

string format: uri-reference

default: about:blank <= 2048 characters

title

required

Short, human-readable summary of the problem type (RFC 9457 Section 3.1.3).

string

<= 256 characters /^[^\p{C}]+$/

status

required

HTTP status code for this occurrence (advisory; same as response status) (RFC 9457 Section 3.1.2).

integer format: int32

>= 100 <= 599

detail

Human-readable explanation specific to this occurrence (RFC 9457 Section 3.1.4).

string

<= 500 characters

instance

URI reference identifying the specific occurrence (RFC 9457 Section 3.1.5).

string format: uri-reference

<= 2048 characters

code

Machine-readable error code for this authentication failure.

string

Allowed values: MISSING_OR_INVALID_TOKEN

Example

{
  "type": "about:blank",
  "code": "MISSING_OR_INVALID_TOKEN"
}

Headers

X-RateLimit-Limit

integer format: int32

>= 1 <= 1000

The maximum number of requests per time window.

X-RateLimit-Remaining

integer format: int32

<= 1000

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset

string format: date-time

<= 29 characters

The time at which the current rate limit window resets.

Retry-After

integer format: int32

>= 1 <= 3600

The number of seconds to wait before retrying the request after receiving a 429 response.

Access-Control-Allow-Origin

string

Allowed values: *

Specifies the allowed origins for CORS.

429

Too many requests. The request rate limit has been exceeded.

Please wait until the rate limit window resets before making additional requests.

application/json

object

type

URI reference identifying the problem type. When absent, “about:blank” per RFC 9457 Section 3.1.1.

string format: uri-reference

default: about:blank <= 2048 characters

title

required

Short, human-readable summary of the problem type (RFC 9457 Section 3.1.3).

string

<= 256 characters /^[^\p{C}]+$/

status

required

HTTP status code for this occurrence (advisory; same as response status) (RFC 9457 Section 3.1.2).

integer format: int32

>= 100 <= 599

detail

Human-readable explanation specific to this occurrence (RFC 9457 Section 3.1.4).

string

<= 500 characters

instance

URI reference identifying the specific occurrence (RFC 9457 Section 3.1.5).

string format: uri-reference

<= 2048 characters

code

Machine-readable error code for rate limit exceeded.

string

Allowed values: RATE_LIMIT_EXCEEDED

Example

{
  "type": "about:blank",
  "code": "RATE_LIMIT_EXCEEDED"
}

Headers

X-RateLimit-Limit

integer format: int32

>= 1 <= 1000

The maximum number of requests per time window.

X-RateLimit-Remaining

integer format: int32

<= 1000

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset

string format: date-time

<= 29 characters

The time at which the current rate limit window resets.

Retry-After

integer format: int32

>= 1 <= 3600

The number of seconds to wait before retrying the request after receiving a 429 response.

Access-Control-Allow-Origin

string

Allowed values: *

Specifies the allowed origins for CORS.

500

Internal server error. The server encountered an unexpected condition that prevented it from fulfilling the request.

Please try again later or contact support if the problem persists.

application/json

object

type

URI reference identifying the problem type. When absent, “about:blank” per RFC 9457 Section 3.1.1.

string format: uri-reference

default: about:blank <= 2048 characters

title

required

Short, human-readable summary of the problem type (RFC 9457 Section 3.1.3).

string

<= 256 characters /^[^\p{C}]+$/

status

required

HTTP status code for this occurrence (advisory; same as response status) (RFC 9457 Section 3.1.2).

integer format: int32

>= 100 <= 599

detail

Human-readable explanation specific to this occurrence (RFC 9457 Section 3.1.4).

string

<= 500 characters

instance

URI reference identifying the specific occurrence (RFC 9457 Section 3.1.5).

string format: uri-reference

<= 2048 characters

code

Machine-readable error code for internal server failure.

string

Allowed values: INTERNAL_ERROR

Example

{
  "type": "about:blank",
  "code": "INTERNAL_ERROR"
}

Headers

X-RateLimit-Limit

integer format: int32

>= 1 <= 1000

The maximum number of requests per time window.

X-RateLimit-Remaining

integer format: int32

<= 1000

The number of requests remaining in the current rate limit window.

X-RateLimit-Reset

string format: date-time

<= 29 characters

The time at which the current rate limit window resets.

Retry-After

integer format: int32

>= 1 <= 3600

The number of seconds to wait before retrying the request after receiving a 429 response.

Access-Control-Allow-Origin

string

Allowed values: *

Specifies the allowed origins for CORS.

Initiate authentication via magic link

Curl Example

Flow

Security

Response

Authorizations

Request Bodyrequired

Examplegenerated

Responses

200

Examplegenerated

Headers

400

Example

Headers

401

Example

Headers

429

Example

Headers

500

Example

Headers

Request Body^required

Example^generated

Example^generated