createIOSStudioSession

POST

/api/v1/oauth/ios-session

curl --request POST \
  --url https://example.com/api/v1/oauth/ios-session \
  --header 'Content-Type: application/json' \
  --data '{ "grant_type": "authorization_code", "client_id": "tilecast-ios", "code": "example", "redirect_uri": "https://example.com", "code_verifier": "example", "refresh_token": "example", "studio_session": false }'

Public and rate-limited. The Tilecast for iOS bootstrap. With authorization_code, exchanges a single-use code issued to tilecast-ios with its PKCE verifier and the callback tilecast-ios://oauth/callback, sets a normal HttpOnly Studio session cookie, and returns the grant’s native credential. With refresh_token, rotates a tilecast-ios refresh token and sets a new Studio session cookie only when studio_session is true. When the session cannot start during a refresh, the rotated credential is still returned with authenticated false and no cookie. A refresh token of any other client is refused before it is consumed. The Studio session belongs to the grant: revoking the grant ends the session, and signing the session out revokes the grant. The app imports the cookie into the configured server’s isolated WebKit data store and keeps the credential out of the web view.

Request Body^required

Media typeapplication/json

object

grant_type

required

string

Allowed values: authorization_code refresh_token

client_id

required

string

Allowed values: tilecast-ios

code

Authorization_code only.

string

redirect_uri

Authorization_code only: tilecast-ios://oauth/callback.

string format: uri

code_verifier

Authorization_code only.

string

refresh_token

Refresh_token only.

string

studio_session

Refresh_token only. Also start a new Studio session and set its cookie, replacing the grant’s earlier session. An authorization_code exchange always sets the cookie.

boolean

Responses

200

The native credential, and a Studio session cookie when authenticated is true

Media typeapplication/json

object

data

required

object

authenticated

required

Whether the response set a Studio session cookie.

boolean

credential

The grant’s native credential. A server released before native API access omits it, and the app then uses Studio only.

object

access_token

required

string

refresh_token

required

string

token_type

required

string

Allowed values: Bearer

expires_at

required

string format: date-time

Example

{
  "data": {
    "credential": {
      "token_type": "Bearer"
    }
  }
}

Headers

Set-Cookie

string

400

Invalid, expired, used, mismatched, or revoked code or refresh token, or a refresh token of another client

401

The account is no longer active

429

Too many authentication attempts