Approve or deny

POST

/approvals/{id}

curl --request POST \
  --url http://127.0.0.1:7700/api/approvals/t3k9x2a1b2.budget.example.spend%3A9f2c41d07a6be315 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "approved": true, "by": "portal" }'

• On the box itself (the default listen address)
• From another device, with a paired device token, when BOX_LISTEN allows it

Answers one approval. The first answer wins: an approval that is already answered is returned unchanged. approved must be true to approve; any other value denies.

From a paired device, the log records the device’s name as who answered, whatever by says. by is used only when the box’s own screen answers. Percent-encode an id that holds spaces, such as one made from Droid’s own question.

An Apple Watch token may approve only up to Settings watchLimitCents, never on a Business box, never a Shopper purchase, and only with auth: wrist. Otherwise the answer is 403 with needs: iphone and the request keeps waiting. A Watch may always deny. On a GurtOS Business box only a person answers, never their own request, only what the policy sends to them and only within their limit. A refusal is 403 with the reason, and the request keeps waiting.

Authorizations

• deviceToken
• accessToken

Parameters

Path Parameters

id

required

string

The approval id. <task id>.budget.<action> is the box’s own spend question, <task id>.task.<key> a question the task asked, <task id>.tool.<call>.ask.<hash> a question a tool asked.

Example

t3k9x2a1b2.budget.example.spend:9f2c41d07a6be315

Request Body^required

Media typeapplication/json

object

approved

required

true approves. Anything else denies.

boolean

by

Who answered, for the log, when the box’s own screen answers. Default api. Ignored from a paired device.

string

auth

How a native app says it checked that it was you. The log keeps it as reported, never as proof.

string

Allowed values: face-id touch-id passcode wrist

Example

{
  "approved": true,
  "by": "portal"
}

Responses

200

The approval after the answer, or as it was if someone answered first.

Media typeapplication/json

object

id

required

<task id>.budget.<action> for the box’s own spend question, <task id>.task.<key> for a question the task asked, <task id>.tool.<call>.ask.<hash> for one a tool asked, <task id>.shadow.<action> for a Business shadow request. The same key asked twice is the same approval. A task can only name keys under task., so it cannot pre-answer the box’s own questions.

string

task

required

string

question

required

The question shown to people.

string

costCents

required

The spending being asked about

number

payee

Who gets paid

string

purpose

What the spend or action is for.

string

state

required

string

Allowed values: pending approved denied

by

Who answered: a paired device’s name, what the box’s own screen sent (such as box screen), jira:<name>, asi1, undo, or task ended. On Business, the person’s name.

string

person

Business: the id of the person who answered.

string

via

Business: the phone or screen the answer came from. A native app’s auth is kept here as reported.

string

askedBy

Business: the id of the person who asked for the task. They may not answer it.

string

route

Business: where the policy sent a request, and why.

object

rule

required

The policy line that matched, such as Over $10,000 goes to the Controller.

string

to

required

Who it goes to as the policy says it: the Controller, IT, any approver.

string

amountCents

required

The amount the rules and limits were checked against

integer

people

required

The people who could approve it when it was asked.

Array<object>

object

id

string

name

string

why

required

One sentence for people.

string

shadow

Business shadow mode: the seat this is a suggestion from.

string

Example

{
  "state": "pending"
}

400

No approval with this id.

Media typeapplication/json

object

error

required

What went wrong

string

Example

{
  "error": "no approval t3k9x2a1b2.task.deploy"
}

401

An outside request with no device token, or with one that is unknown or revoked.

Media typeapplication/json

object

error

required

What went wrong

string

Example

{
  "error": "pair this phone with this computer first"
}

403

A Watch token over its limit, a Business refusal, or an app’s window answering another app’s request. The Watch and window refusals carry needs.

Media typeapplication/json

object

error

required

string

needs

Where it may be answered instead: iphone, or shell (GurtOS itself, not an app window).

string

Allowed values: iphone shell

task

With needs: shell, the task whose request it is.

string

Example

{
  "error": "Approve this on your iPhone: the Watch approves up to $25.00.",
  "needs": "iphone"
}