---
title: "Create a message sign-in URL"
method: POST
path: "/v1/auth/sign-in/message-url"
tags: ["Auth"]
---

# Create a message sign-in URL

`POST /v1/auth/sign-in/message-url`

## Request

- Base URL: `https://api.configure.dev`
- URL: `https://api.configure.dev/v1/auth/sign-in/message-url`
- Auth: API key in header `X-API-Key`

Creates a hosted sign-in, reconnect, or permission-review URL for a message-channel sender. If a messageLinePhone or agentPhone is supplied, it must be an active registered message line for the acting agent and channel. Code-bearing responses require verified provider-signed message sender proof; without it, the endpoint returns the plain sign-in.me handoff and creates no code.

## Headers

- `X-Agent` string

## Request body

- SignInMessageUrlRequest
  - `reason` 'signin' | 'reconnect' | 'permissions'
  - `channel` string, required
  - `subject` SignInMessageUrlSubject, required
    - `key` string, required: Stable adapter subject key for the message sender.
    - `externalId` string, required: Developer-scoped external ID used before the sender links Configure.
    - `senderId` string
  - `thread` SignInMessageUrlThread
    - `key` string
    - `spaceId` string
    - `messageId` string
  - `messageSenderProof` string: Provider-signed evidence that the message sender/thread claim is authentic. A code-bearing URL is returned only when Configure can verify this value.
  - `connectors` string[]
  - `displayName` string
  - `agentLogo` string
  - `theme` 'light' | 'dark'
  - `messageLinePhone` string: Current provider-owned message line that users return to after hosted sign-in. Must already be registered for the acting agent and channel.
  - `agentPhone` string: Alias for messageLinePhone. Prefer this when resolving the agent's current line from the messaging provider.
  - `messageBody` string: Suggested SMS/iMessage body for returning to the agent.
  - `messageCompleteUrl` string: Optional trusted completion endpoint called by hosted sign-in after approval.
  - `journeyId` string: Optional application journey identifier used to map hosted completion back to a message thread.
  - `returnMode` 'message'
  - `idempotencyKey` string

## Response `200`

Hosted message sign-in URL.

- union
  - SignInMessageUrlMintedResponse
    - `mode` 'minted', required
    - `url` string, required
    - `code` string, required
    - `reason` 'signin' | 'reconnect' | 'permissions', required
    - `expiresAt` string, date-time, required
    - `idempotencyKey` string
  - SignInMessageUrlPlainResponse
    - `mode` 'plain', required
    - `url` string, required
    - `reason` 'signin' | 'reconnect' | 'permissions', required
    - `fallbackReason` 'sender_proof_missing' | 'sender_proof_invalid' | 'sender_proof_unsupported', required
    - `idempotencyKey` string

## Other responses

- `400`: Request shape is invalid.
- `403`: Forbidden. Common causes include secret_key_required, token_wrong_type, approval_required, or access_denied.

---

[API](https://skmtc.dev/configure/apis/configure-http-api.md) · [All operations](https://skmtc.dev/configure/apis/configure-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/configure/apis/configure-http-api/revisions/ec760a9533d2?raw)