Embedded Tax API

Hosted Portal

Server-to-server partner endpoints under https://api.awaken.tax/api.

POST

/access-tokens

Mint a short-lived access token for the embedded portal

Field	Type	Required	Notes
`referenceId`	string	Yes
`expiresInSeconds`	integer	No	min 1, max 86400
`email`	string	No	email

Request body

{
  "referenceId": "user-42",
  "email": "user@example.com",
  "expiresInSeconds": 3600
}

Example response

{
  "type": "success",
  "message": "Access token created successfully",
  "data": {
    "accessToken": "<access-token-jwt>",
    "tokenType": "Bearer",
    "referenceId": "user-42",
    "expiresInSeconds": 3600,
    "expiresAt": "2026-07-30T00:42:57.891Z",
    "portalUrl": "https://embed.awaken.tax/portal?code=user-42&token=<access-token-jwt>&email=user%40example.com"
  }
}

Status	Meaning
`200`	Token minted. Open portalUrl in the browser, or use accessToken as a Bearer token.
`400`	Invalid body. referenceId is missing, or email or expiresInSeconds is malformed.
`401`	Partner credentials missing or invalid.
`403`	An access token cannot mint another access token. Use a partner credential.
`404`	No client with that referenceId belongs to this partner.

curl

curl -X POST "https://api.awaken.tax/api/access-tokens" \
  -H "x-client-id: $AWAKEN_CLIENT_ID" \
  -H "x-api-secret: $AWAKEN_API_SECRET" \
  -H "content-type: application/json" \
  --data '{ "referenceId": "user-42", "email": "user@example.com", "expiresInSeconds": 3600 }'

POST

/links

Create a hosted portal link

Field	Type	Required	Notes
`wallets`	array	Yes

Request body

{
  "wallets": [
    {
      "address": "0xabc…",
      "name": "Primary wallet"
    }
  ]
}

Status	Meaning
`200`	Existing link
`201`	Link created
`400`	Validation failed

curl

curl -X POST "https://api.awaken.tax/api/links" \
  -H "x-client-id: $AWAKEN_CLIENT_ID" \
  -H "x-api-secret: $AWAKEN_API_SECRET" \
  -H "content-type: application/json" \
  --data '{ "wallets": [ { "address": "0xabc…", "name": "Primary wallet" } ] }'

POST

/links/email

Email a hosted portal link

Field	Type	Required	Notes
`wallets`	array	Yes
`email`	string	Yes	email

Request body

{
  "email": "user@example.com",
  "wallets": [
    {
      "address": "0xabc…"
    }
  ]
}

Status	Meaning
`200`	Email accepted
`429`	Recipient daily limit reached

curl

curl -X POST "https://api.awaken.tax/api/links/email" \
  -H "x-client-id: $AWAKEN_CLIENT_ID" \
  -H "x-api-secret: $AWAKEN_API_SECRET" \
  -H "content-type: application/json" \
  --data '{ "email": "user@example.com", "wallets": [ { "address": "0xabc…" } ] }'