POST /configuration

Search…

POST /configuration

API reference for the "/configuration" endpoint.

If an app supports authentication and has a publish extension, Canva sends a POST request to the following endpoint when a user opens the extension:
<authentication_base_url>/configuration
The purpose of this request is to check if the user is authenticated with the destination platform.
If the user is authenticated, the extension continues to load. If the user is not authenticated, Canva renders a Connect button. The user can click this button to start the authentication flow.
To learn more, refer to Authentication.
Notes
Extensions must respond to this request within 8 seconds.
When sending this request, Canva replaces <authentication_base_url> with the app's Authentication base URL. You can configure the Authentication base URL via the app's Authentication page.
Extensions should meet the UX guidelines.
Request
Endpoint
POST <authentication_base_url>/configuration
Headers
Property
Type
Required
Description
X-Canva-Signatures
string
Yes
A comma-separated list of request signatures. The name of this header is sometimes lowercase (e.g. x-canva-signatures).
X-Canva-Timestamp
string
Yes
The UNIX timestamp (in seconds) of when Canva sent the request. The name of this header is sometimes lowercase (e.g. x-canva-timestamp).
Body
Properties
Property
Type
Required
Description
user
string
Yes
The ID of the user.
brand
string
Yes
The ID of the user's team.
Example
{
  "user": "<user>",
  "brand": "<brand>"
}
Responses
200 - Success (user is authenticated)
The response the app provides when the user is authenticated with the destination platform.
Properties
Property
Type
Required
Description
type
"SUCCESS"
Yes
The type of response.
labels
array
Yes
The extension points the user has authenticated with.
Example
{
  "labels": [],
  "type": "SUCCESS"
}
200 - Error (user not authenticated)
The response the app provides when the user is not authenticated with the destination platform.
Properties
Property
Type
Required
Description
type
"ERROR"
Yes
The type of response.
errorCode
"CONFIGURATION_REQUIRED"
Yes
An error code that describes what went wrong.
Example
{
  "type": "ERROR",
  "errorCode": "CONFIGURATION_REQUIRED"
}
200 - Error (other)
The response the app provides when an error occurs.
Properties
Property
Type
Required
Description
type
"ERROR"
Yes
The type of response.
errorCode
string
Yes
An error code that describes what went wrong. Enum: "FORBIDDEN", "INTERNAL_ERROR", "INVALID_REQUEST", "NOT_FOUND", "TIMEOUT"
Example
{
  "type": "ERROR",
  "errorCode": "<error_code>"
}
401 - Invalid request signature or timestamp
An extension must verify the request signature and timestamp of all incoming requests. When an extension can't verify either of these values, it must reject the request with a 401 status code.

Server API - Previous

GET /apps/configured

Next - Server API

POST /configuration/delete

Last modified 2mo ago

Copy link

Outline

200 - Success (user is authenticated)

200 - Error (user not authenticated)

200 - Error (other)

401 - Invalid request signature or timestamp