Warpwire Keys API

The Warpwire keys API allows you to create connections between Warpwire and 3rd party tools. Currently, the API supports creating OAuth keys and LTI 1.0/1.1 keys. You can also find out information about or modify existing keys. For more details on external keys, please see our External Keys support guide.

All API calls require authentication and the authenticated user must have institutional administrator privileges.

GET Method: Retrieve list of all external keys

/api/keys/

URL Parameters

None

Request Parameters

Parameter	Type	Description	Required?	Default
`page`	number	Page number of results, starting at 0	No	`0`
`limit`	number	Number of results per page, minimum 1, maximum 50	No	`10`
`sort`	string	Field to sort on (`name`, `type`, `creation`, `expiration`, `enabled`)	No	`name`
`order`	string	Direction of sort (`asc` or `desc`)	No	`asc`

Response Codes

200: success
400: one or more of the request parameters are invalid
401: user is not authenticated
403: user is not an institutional admin

Error Response

    {
        "code":400,
        "message": "Invalid value for \"order\""
    }

Success Response

    {
        "list": [
        {
          "id": number,
          "name": string,
          "type": string,
          "creation": string,
          "expiration": string|null
          "enabled": boolean
        },
        ...
      ],
      "links": {
        "self": string,
        "previous": string|null,
        "next": "string|null
      }
    }

Field	Type	Description	Example
`list`	array of objects
`list[].id`	number	LTI key ID	`3`
`list[].name`	string	Key itself	`"lti:client:moodle"`
`list[].type`	string	Type of key (OAuth2, LTI 1.1/1.2)	`"lti1_2"`
`list[].creation`	string	Timestamp of when key was created	`"2021-04-06T14:08:49-04:00"`
`list[].expiration`	string, null	Date string of when key will expire, if set	`"2024-12-01"`
`list[].enabled`	boolean	Whether key is enabled	`true`
`links.self`	string	URL to current page of results
`links.previous`	string, null	URL to previous page of results, or null if no previous page
`links.next`	string, null	URL to next page of results, or null if no next page

GET Method: Retrieve information about a single external key

/api/keys/[id]/

URL Parameters

Parameter	Type	Description	Required?	Default
`id`	number	Key ID	Yes

Request Parameters

None

Response Codes

200: success
401: user is not authenticated
403: user is not an institutional admin

Error Response

    {
        "code":400,
        "message": "Invalid value for \"order\""
    }

Success Response

    {
        "id": number,
        "name": string,
        "type": string,
        "creation": string,
        "expiration": string|null
        "enabled": boolean,
        ...
    }

Field	Type	Description	Example
`id`	number	LTI key ID	`3`
`name`	string	Key itself	`"lti:client:moodle"`
`type`	string	Type of key (OAuth2, LTI 1.1/1.2)	`"lti1_2"`
`creation`	string	Timestamp of when key was created	`"2021-04-06T14:08:49-04:00"`
`expiration`	string, null	Date string of when key will expire, if set	`"2024-12-01"`
`enabled`	boolean	Whether key is enabled	`true`
`domain_count`	number	Not yet documented (OAuth2 only)	`2`
`unique_identifier`	boolean	The unique identifier of the user accout within your LMS (LTI 1.1/1.2 only)	`true`
`authorization_source`	string	Whether the LTI key is allowed to sign users in (LTI 1.1/1.2 only)	`true`
`grant_authorization`	string	If a user does not have access to a resource, the LTI key allows the LMS to grant access to resources within Warpwire. If `false`, you must then use the Warpwire share function to grant access. If `true`, the LMS will automatically provide access to resources within Warpwire. (LTI 1.1/1.2 only) (LTI 1.1/1.2 only)	`true`
`custom_route`	string, null	Not yet documented (LTI 1.1/1.2 only)	`null`
`append_key_user_identifier`	boolean, null	If you are using multiple LMS's and the user's unique identifier is not synchronized across all the LMS's, setting this to `true` allows Warpwire to know which LMS the user is coming from. Enabling will allow all users to sign onto Warpwire without their accounts colliding because Warpwire will uniquely identify every key so that any user is treated as a distinct user (LTI 1.1/1.2 only)	`false`
`prepend_key_course_identifier`	boolean, null	If there are duplicate courses within multiple systems they will be uniquely identified within Warpwire (LTI 1.1/1.2 only)	`false`
`prepend_key_course_identifier_legacy_support`	boolean, null	Legacy mode for preceding (LTI 1.1/1.2 only)	`false`
`restrict_course_access`	boolean, null	Whether only certain courses to have access to Warpwire. If `true`, you must create a group with a matching unique identifier to the course to enable access to a Media Library (LTI 1.1/1.2 only)	`false`
`restrict_course_access_case_sensitive`	boolean, null	If you want Warpwire to check for casing in courses when restricting course access (LTI 1.1/1.2 only)	`false`
`restrict_course_search_field`	boolean, null	Not documented (LTI 1.1/1.2 only)	`false`
`grade_submission`	boolean, null	Whether Warpwire will send grades back to the LMS (LTI 1.1/1.2 only)	`false`

Notes:

Some fields are only included for certain types. This is notated in the description column above.
Many of the LTI 1.1/1.2 fields can be boolean or null. If the value is null, that is considered "Not Set" (as it would appear in the admin tool). Null is functionally equivalent to false with respect to how the site behaves. We reserve the right to remove the nullability in the future and expose just true and false.

POST Method: Create a new external key

/api/keys/

URL Parameters

None

Request Parameters

None

Body Parameters

Parameters are expected in application/x-www-form-urlencoded format.

Parameter	Type	Description	Required?	Default
`name`	string	Key name, which is used as the "key" of the key/secret pair	Yes
`type`	string	Type of key (`oauth2` or `lti1_2`)	Yes
`expiration`	string, null	Expiration date in "Y-m-d" format	No	`null`
`client_endpoint`	string		If type is `oauth2`
`client_domain`	string		If type is `oauth2`
`client_name`	string		If type is `oauth2`
`unique_identifier`	string	The unique identifier of the user accout within your LMS	If type is `lti1_2`
`authentication_source`	boolean	Whether the LTI key is allowed to sign users in	If type is `lti1_2`
`grant_authorization`	boolean	If a user does not have access to a resource, the LTI key allows the LMS to grant access to resources within Warpwire. If `false`, you must then use the Warpwire share function to grant access. If `true`, the LMS will automatically provide access to resources within Warpwire	If type is `lti1_2`
`append_key_user_identifier`	boolean, null	If you are using multiple LMS's and the user's unique identifier is not synchronized across all the LMS's, setting this to `true` allows Warpwire to know which LMS the user is coming from. Enabling will allow all users to sign onto Warpwire without their accounts colliding because Warpwire will uniquely identify every key so that any user is treated as a distinct user	No (Only allowed if type is `lti1_2`)
`prepend_key_course_identifier`	boolean, null	If there are duplicate courses within multiple systems they will be uniquely identified within Warpwire	No (Only allowed if type is `lti1_2`)
`prepend_key_course_identifier_legacy_support`	boolean, null	Do not use	No (Only allowed if type is `lti1_2`)
`restrict_course_access`	boolean, null	Whether only certain courses to have access to Warpwire. If `true`, you must create a group with a matching unique identifier to the course to enable access to a Media Library.	No (Only allowed if type is `lti1_2`)
`restrict_course_access_case_sensitive`	boolean, null	If you want Warpwire to check for casing in courses when restricting course access	No (Only allowed if type is `lti1_2`)
`grade_submission`	boolean, null	Whether Warpwire will send grades back to the LMS	No (Only allowed if type is `lti1_2`)

Response Codes

200: success
400: one or more parameters are invalid
401: user is not authenticated
403: user is not an institutional admin

Error Response

     {
        "code": 400,
         "message": "Invalid value for \"name\""
    }

Success Response

    {
        "id": number,
        "name": string,
        "type": string,
        "creation": string,
        "expiration": string|null
        "enabled": boolean,
        ...
    }

Field	Type	Description	Example
`id`	number	LTI key ID	`3`
`name`	string	Key itself	`"lti:client:moodle"`
`type`	string	Type of key (OAuth2, LTI 1.1/1.2)	`"lti1_2"`
`creation`	string	Timestamp of when key was created	`"2021-04-06T14:08:49-04:00"`
`expiration`	string, null	Date string of when key will expire, if set	`"2024-12-01"`
`enabled`	boolean	Whether key is enabled	`true`
`domain_count`	number	Not yet documented (OAuth2 only)	`2`
`unique_identifier`	string	The unique identifier of the user accout within your LMS. (LTI 1.1/1.2 only)	`"userId"`
`authorization_source`	boolean	Whether the LTI key is allowed to sign users in. (LTI 1.1/1.2 only)	`true`
`grant_authorization`	boolean	If a user does not have access to a resource, the LTI key allows the LMS to grant access to resources within Warpwire. If `false`, you must then use the Warpwire share function to grant access. If `true`, the LMS will automatically provide access to resources within Warpwire. (LTI 1.1/1.2 only)	`true`
`custom_route`	string, null	Not documented (LTI 1.1/1.2 only)	`null`
`append_key_user_identifier`	boolean, null	If you are using multiple LMS's and the user's unique identifier is not synchronized across all the LMS's, setting this to `true` allows Warpwire to know which LMS the user is coming from. Enabling will allow all users to sign onto Warpwire without their accounts colliding because Warpwire will uniquely identify every key so that any user is treated as a distinct user. (LTI 1.1/1.2 only)	`false`
`prepend_key_course_identifier`	boolean, null	If there are duplicate courses within multiple systems they will be uniquely identified within Warpwire. (LTI 1.1/1.2 only)	`false`
`prepend_key_course_identifier_legacy_support`	boolean, null	Legacy mode for preceding (LTI 1.1/1.2 only)	`false`
`restrict_course_access`	boolean, null	Whether only certain courses to have access to Warpwire. If `true`, you must create a group with a matching unique identifier to the course to enable access to a Media Library (LTI 1.1/1.2 only)	`false`
`restrict_course_access_case_sensitive`	boolean, null	If you want Warpwire to check for casing in courses when restricting course access (LTI 1.1/1.2 only)	`false`
`restrict_course_search_field`	boolean, null	Not documented (LTI 1.1/1.2 only)	`false`
`grade_submission`	boolean, null	Whether Warpwire will send grades back to the LMS. (LTI 1.1/1.2 only)	`false`
`secret`	boolean, null	Autogenerated secret for key	`"abcd1234"`

Notes:

Some fields are only included for certain types. This is notated in the description column above.
Many of the LTI 1.1/1.2 fields can be boolean or null. If the value is null, that is considered "Not Set" (as it would appear in the admin tool). Null is functionally equivalent to false with respect to how the site behaves. We reserve the right to remove the nullability in the future and expose just true and false.
The secret is returned only by this POST request. It cannot be retrieved later. It is imperative that you save the secret from this result or a new key will have to be created.

PUT Method: Update an existing external key

/api/keys/[id]/

URL Parameters

Parameter	Type	Description	Required?	Default
`id`	number	Key ID	Yes

Request Parameters

None

Body Parameters

Parameters are expected in application/x-www-form-urlencoded format.

Parameter	Type	Description	Required?
`name`	string	Key name, which is used as the "key" of the key/secret pair	No
`expiration`	string, null	Expiration date in "Y-m-d" format	No
`enabled`	boolean	Whether key is enabled	No
`client_endpoint`	string	Not yet documented	No (only allowed if type is `oauth2`)
`client_domain`	string	Not yet documented	No (only allowed if type is `oauth2`)
`client_name`	string	Not yet documented	No (only allowed if type is `oauth2`)
`unique_identifier`	string	The unique identifier of the user accout within your LMS	No (only allowed if type is `lti1_2`)
`authentication_source`	boolean	Whether the LTI key is allowed to sign users in	No (only allowed if type is `lti1_2`)
`grant_authorization`	boolean	If a user does not have access to a resource, the LTI key allows the LMS to grant access to resources within Warpwire. If `false`, you must then use the Warpwire share function to grant access. If true, the LMS will automatically provide access to resources within Warpwire	No (only allowed if type is `lti1_2`)
`append_key_user_identifier`	boolean, null	If you are using multiple LMS's and the user's unique identifier is not synchronized across all the LMS's, setting this to `true` allows Warpwire to know which LMS the user is coming from. Enabling will allow all users to sign onto Warpwire without their accounts colliding because Warpwire will uniquely identify every key so that any user is treated as a distinct user	No (only allowed if type is `lti1_2`)
`prepend_key_course_identifier`	boolean, null	If there are duplicate courses within multiple systems they will be uniquely identified within Warpwire	No (only allowed if type is `lti1_2`)
`prepend_key_course_identifier_legacy_support`	boolean, null	Do not use	No (only allowed if type is `lti1_2`)
`restrict_course_access`	boolean, null	Whether only certain courses to have access to Warpwire. If true, you must create a group with a matching unique identifier to the course to enable access to a Media Library	No (only allowed if type is `lti1_2`)
`restrict_course_access_case_sensitive`	boolean, null	If you want Warpwire to check for casing in courses when restricting course access	No (only allowed if type is `lti1_2`)
`grade_submission`	boolean, null	Whether Warpwire will send grades back to the LMS	No (only allowed if type is `lti1_2`)

Notes:

Empty string or the string null passed as a parameter value is treated as null and will result in the modification of data (if allowed for that parameter).
Parameters not provided at all do not result in changing the corresponding field at all. As such, the default column is empty for all parameters.

Response Codes

200: success
400: one or more parameters are invalid
401: user is not authenticated
403: user is not an institutional admin

Error Response

     {
        "code": 400,
         "message": "Invalid value for \"name\""
    }

Success Response

    {
        "id": number,
        "name": string,
        "type": string,
        "creation": string,
        "expiration": string|null
        "enabled": boolean,
        ...
    }

Field	Type	Description	Example
`id`	number	LTI key ID	`3`
`name`	string	Key itself	`"lti:client:moodle"`
`type`	string	Type of key (OAuth2, LTI 1.1/1.2)	`"lti1_2"`
`creation`	string	Timestamp of when key was created	`"2021-04-06T14:08:49-04:00"`
`expiration`	string, null	Date string of when key will expire, if set	`"2024-12-01"`
`enabled`	boolean	Whether key is enabled	`true`
`domain_count`	number	Not yet documented (OAuth2 only)	`2`
`unique_identifier`	string	NThe unique identifier of the user accout within your LMS (LTI 1.1/1.2 only)	`"userId"`
`authorization_source`	boolean	Whether the LTI key is allowed to sign users in (LTI 1.1/1.2 only)	`true`
`grant_authorization`	boolean	If a user does not have access to a resource, the LTI key allows the LMS to grant access to resources within Warpwire. If false, you must then use the Warpwire share function to grant access. If true, the LMS will automatically provide access to resources within Warpwire(LTI 1.1/1.2 only)	`true`
`custom_route`	string, null	Not yet documented (LTI 1.1/1.2 only)	`null`
`append_key_user_identifier`	boolean, null	If you are using multiple LMS's and the user's unique identifier is not synchronized across all the LMS's, setting this to `true` allows Warpwire to know which LMS the user is coming from. Enabling will allow all users to sign onto Warpwire without their accounts colliding because Warpwire will uniquely identify every key so that any user is treated as a distinct user. (LTI 1.1/1.2 only)	`false`
`prepend_key_course_identifier`	boolean, null	If there are duplicate courses within multiple systems they will be uniquely identified within Warpwire (LTI 1.1/1.2 only)	`false`
`prepend_key_course_identifier_legacy_support`	boolean, null	Legacy mode for preceding (LTI 1.1/1.2 only)	`false`
`restrict_course_access`	boolean, null	Whether only certain courses to have access to Warpwire. If `true`, you must create a group with a matching unique identifier to the course to enable access to a Media Library (LTI 1.1/1.2 only)	`false`
`restrict_course_access_case_sensitive`	boolean, null	If you want Warpwire to check for casing in courses when restricting course access (LTI 1.1/1.2 only)	`false`
`restrict_course_search_field`	boolean, null	Not yet documented (LTI 1.1/1.2 only)	`false`
`grade_submission`	boolean, null	Whether Warpwire will send grades back to the LMS (LTI 1.1/1.2 only)	`false`

Notes:

Some fields are only included for certain types. This is notated in the description column above.
Many of the LTI 1.1/1.2 fields can be boolean or null. If the value is null, that is considered "Not Set" (as it would appear in the admin tool). Null is functionally equivalent to false with respect to how the site behaves. We reserve the right to remove the nullability in the future and expose just true and false.

View Developer APIs page