Skip to content
SurveyRock Support

Create API token

POST
/tokens
curl --request POST \
  --url https://app.surveyrock.com/api/v1/tokens \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "scopes": [ "example" ], "is_live": false, "expires_at": "2026-04-15T12:00:00Z" }'

Create a new API token for the current account. The token value is only returned once, at creation time.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

Token creation data

Media typeapplication/json

API token creation request

object
name
required

Token name

string
scopes

Token scopes (defaults to read-only scopes)

Array<string>
is_live

Whether this is a live token

boolean
expires_at

Token expiration time

string format: date-time
nullable

Responses

Section titled “Responses”

200

Section titled “200”

Token created successfully

Media typeapplication/json
object
success
boolean
data

API token creation response

object
token

The actual token value (only shown once)

string
id

Token ID

string
name

Token name

string
scopes

Token scopes

Array<string>
expires_at
string format: date-time
nullable
created_at
string format: date-time
meta

Standard response metadata

object
timestamp

Response timestamp in ISO 8601 format

string format: date-time
version

API version

string
requestId

Unique request identifier

string
Example
{
  "success": true,
  "meta": {
    "version": "3.0"
  }
}

400

Section titled “400”

Bad request - missing name, invalid scopes, or invalid expiration

Media typeapplication/json

Standard error response format

object
success
boolean
error
object
code

Stable, snake_case domain code – see ApiErrorHandler::EXCEPTION_MAP and DomainException

string
message

Human-readable error message

string
suggestion

Imperative recovery hint for this domain code – see ApiErrorHandler::DOMAIN_CODE_SUGGESTIONS

string
retryable

Whether retrying the identical request might succeed without any change on the caller’s end

boolean
details

Additional, code-specific error details

object
meta

Standard response metadata

object
timestamp

Response timestamp in ISO 8601 format

string format: date-time
version

API version

string
requestId

Unique request identifier

string
Example
{
  "success": false,
  "error": {
    "code": "survey_not_found"
  },
  "meta": {
    "version": "3.0"
  }
}

401

Section titled “401”

Unauthorized - invalid or missing token

Media typeapplication/json

Standard error response format

object
success
boolean
error
object
code

Stable, snake_case domain code – see ApiErrorHandler::EXCEPTION_MAP and DomainException

string
message

Human-readable error message

string
suggestion

Imperative recovery hint for this domain code – see ApiErrorHandler::DOMAIN_CODE_SUGGESTIONS

string
retryable

Whether retrying the identical request might succeed without any change on the caller’s end

boolean
details

Additional, code-specific error details

object
meta

Standard response metadata

object
timestamp

Response timestamp in ISO 8601 format

string format: date-time
version

API version

string
requestId

Unique request identifier

string
Example
{
  "success": false,
  "error": {
    "code": "survey_not_found"
  },
  "meta": {
    "version": "3.0"
  }
}

403

Section titled “403”

Forbidden - insufficient permissions

Media typeapplication/json

Standard error response format

object
success
boolean
error
object
code

Stable, snake_case domain code – see ApiErrorHandler::EXCEPTION_MAP and DomainException

string
message

Human-readable error message

string
suggestion

Imperative recovery hint for this domain code – see ApiErrorHandler::DOMAIN_CODE_SUGGESTIONS

string
retryable

Whether retrying the identical request might succeed without any change on the caller’s end

boolean
details

Additional, code-specific error details

object
meta

Standard response metadata

object
timestamp

Response timestamp in ISO 8601 format

string format: date-time
version

API version

string
requestId

Unique request identifier

string
Example
{
  "success": false,
  "error": {
    "code": "survey_not_found"
  },
  "meta": {
    "version": "3.0"
  }
}

422

Section titled “422”

Token creation failed

Media typeapplication/json

Standard error response format

object
success
boolean
error
object
code

Stable, snake_case domain code – see ApiErrorHandler::EXCEPTION_MAP and DomainException

string
message

Human-readable error message

string
suggestion

Imperative recovery hint for this domain code – see ApiErrorHandler::DOMAIN_CODE_SUGGESTIONS

string
retryable

Whether retrying the identical request might succeed without any change on the caller’s end

boolean
details

Additional, code-specific error details

object
meta

Standard response metadata

object
timestamp

Response timestamp in ISO 8601 format

string format: date-time
version

API version

string
requestId

Unique request identifier

string
Example
{
  "success": false,
  "error": {
    "code": "survey_not_found"
  },
  "meta": {
    "version": "3.0"
  }
}