Generating an API key
Overview
CYPHER Learning’s API allows you to integrate your learning platform with third party tools and systems that help elevate your user’s experience. The CYPHER API is the intermediary between the features of the learning platform and your website or software. The API allows you to share data and trigger events that provide nearly endless automation possibilities.
API Versions
CYPHER Learning currently supports two API instances: versions 1.0 and 3.0.
NOTE: API 1.0 will be supported until full parity with API 3.0 is achieved. For more information contact your Account Executive.The platform's API uses modern best practices which supports the Open API 3.0 specification and works with popular API invocation tools, such as Postman. The API follows the REST (Representational State Transfer) principles and is based on the following principles:
- Use GET for accessing items
- Use POST for adding and updating items
- Support an 'include' feature to include associated items
- Support a 'batch' feature to run multiple requests in a single call
- Rate limiting for server protection
- Support pagination of small datasets using $offset, with the option to include $order
- Support fast pagination of large datasets using $after
- Support $limit to specify the max number of items returned in a list operation
- Support $include to include related items in the returned values
- Support $ref to reference related items in a request or response
For more details on using either API version:
- API 1.0 (Legacy): Visit the API 1.0 (Legacy) knowledge base article.
- API 3.0: Visit the API 3.0 knowledge base article.
How to create and configure an API key
By default, API access to your site is disabled. To enable API, you must first install the API app. To install the API app:
- Click Admin from the primary navigation menu.
- Click App center from the fly-out menu.
The App center displays.
- Search for API in the search field.
- Click Install on the API app you plan to use.
- API 3.0 is recommended.
Generating an API key
An API key is a unique, secret token used to authenticate requests to an API and identify the calling application. It enables the service to authorize access, track usage, and enforce rate limits or billing.
Only Super administrators can create API keys on the learning platform. They have the ability to edit, delete, and add API keys as needed. In addition, each API key can have an optional expiry date, restricted set of IPs, and/or a restricted set of operations, allowing for the creation of different keys for different situations.
To create a new API key, super administrators:
- Click Admin from the primary navigation menu.
- Click API from the fly-out menu.
- Click Add.
The Add pop-up displays.
- Enter a Name for the API key.
- Select the API Version you wish to use.
- Click Save.
When an API key is created, it is not enabled and has no restrictions. To enable the API key:
- Click the Enabled checkbox.
Viewing and configuring an API key
To view and configure an API key:
- Click the API key name.
The API key page displays, and includes the API key Name and Secret key. If you would like to rename the key:
- Click Rename.
The Edit pop-up displays.
- Type the new name for the API key.
- Click Save.
You can also regenerate a new secret key. To create a new key:
- Click Regenerate key.
- Note that this invalidates the previously used secret key.
By default, the super administrator who created the key is listed in the Execute as field. To change the user listed in the Execute as field:
- Click Change User.
The Select users pop-up displays.
- Select a user.
- Click Select.
You can add restrictions to the API key, such as specifying an expiration date, only allowing certain IPs, and editing the scope of the API calls. To set restrictions for the API key:
- Click Edit in the Restrictions section.
The Edit page displays.
By default, the API key never expires. To add an expiration date to the API key:
- Select the At specified date radio button under the Expires setting.
- Click the Calendar
icon to select a date when the API key will expire.
The Edit page also allows you to restrict access to specific IP address. By default, all IPs are allowed. To only allow certain IPs:
- Click the Specified radio button under the Allow IPs setting.
- Enter an IP address.
- Click add.
- Note that you can add as many IPs as needed.
You can also restrict the set of operations of the API key by defining its scope. By default, all HTTP Verbs are included in the key configuration. To restrict the API key to specific verbs:
- Click the Specified radio button under the HTTP Verbs setting.
- Only select the verbs you would want to allow for the API key.
You can further limit the scope of the API key by specifying which endpoints it can access. By default, an API key has access to all endpoints. To restrict access to specific endpoints:
- Click the Specified radio button for the Endpoint setting.
- Select the endpoints you would like to enable for the API key.
Once you have configured the API key:
- Click Save.
The API key is updated and the selected restrictions are displayed in the Restrictions section.
Administrator view
Administrators can see a list of the available API keys, but cannot add, edit or delete them.
To request a new API key or for modifications to be made to existing API keys, administrators must contact the Super administrator of their platform.
To view a list of available API Keys, administrators:
- Click Admin from the primary navigation menu.
- Click API from the fly-out menu.
The list of available API keys display, along with their API version number, the date they were created, their expiration date, the number of associated calls, and the number of associated errors.
- To see more information about a specific API key, click the API key name.
The API key displays, along with restriction and statistic details. Note that the secret key is masked.
- Administrators must contact their Super administrator for the secret key.
Related Articles
Best practices for administrators
Overview The following are recommended best practices for new administrators. Choose a short URL Keep your URL short—ideally fewer than 10 characters. For example, if your company is called 'The Academy of Digital Photography,' a URL like 'ADP' is ...Profile settings for administrators
Overview Every user has a profile page that includes various information such as their basic info, their account details, their friends, photos, social media links, and more. The information that is visible depends on the user's role and the portal's ...Zapier
Overview Zapier is a popular, easy-to-use service that lets you to integrate more than 1,500 apps using a point-and-click interface - no programming required. The CYPHER Learning app on Zapier allows you to connect your portal with these apps to ...E-commerce
Overview E-commerce allows you to sell your learning products online. By enabling e-commerce, you can turn your platform into a digital storefront! Visitors and users can browse your course catalog, add courses to their shopping cart, and then pay ...MailChimp
Overview The Mailchimp integration gives administrators an end-to-end email integration for email marketing and customized Learner email messages. Administrators can import Mailchimp contacts into the portal, and they can export user lists from their ...