Summary

Below you'll find a summary of how to setup your API! The 5 main steps are in 2 categories excluding the prerequisites.

• Prerequisites
• Athennian Admins
  • Create Key
  • Assign Access
  • Provide Documentation
• API Developers
  • Create Request
  • Test Setup

Prerequisites

• Feature
  • If you have not already, confirm with your Athennian contact that this feature is currently turned on for the specific environment URL you are wanting to setup
    • Examples:
      • Production: name.athennian.com
      • Sandbox: name.test.athennian.com
• Developer(s)
  • Be sure to confirm that your development team is able and ready to assist with the second part of this setup.

Athennian Admins:

Below you'll find the first 3 steps for setting up your API! These are done by one of your Athennian Admins. Optional considerations listed at the end of each section.

#1 Create Key

This step is like creating a user without any access.

1. Log into the Athennian environment you wish to use.
2. Navigate to: Menu > Access > API Keys > New +
3. Provide a Key Name > Assign Access Groups (required) > Generate
4. You'll then be shown a popup with your key.

Optional Considerations:

• Groups
  • Roles are set to User and cannot be changed when creating keys.
  • If required, you can create a key, and provide the access group(s) later.
  • API Keys cannot have System Roles directly.
•  Expiration
  • By default, Access Expiry will be set to Never. You can set a future date for access to expire.
  • Once the record expires, it is automatically revoked (see below).
•  Storage
  • Please be sure to copy and save your key security. It cannot be shown again via Athenninan for security reasons.
• Metadata
  • Once the key is created you'll see a variety of associated data points including: Name, System Role, Created Date, Created By, Archived Date, Archived By.
  • You can search and filter this data much the same way you do throughout the app.
• Names
  • The name should generally provide any context necessary so your team knows how to manage this key in the future. For example, the name could include the relevant environment, developer, use case, etc (e.g. Andrew's Production Google Integration).
  • Keys cannot be renamed or used more than once even if it's revoked (#HOOT-5528).
• Revoke
  • Keys can be revoked. When this happens they are removed from your API Keys list entirely and the key name cannot be reused.

#2 Update Access (Optional)

Here you can change application and data access to the new key.

1. Navigate to: Select Key > Access Groups > Add
2. Select access group(s) > Next > Add

Optional Considerations:

• Groups
  • (Recommended) Always use role User.
  • In some cases, you may first want to create specific access group(s) specific for your key(s). This can happen any time before this step.
• Edit
  • On the main page, you cannot edit access once it's created. Changes will need to be done through a new access record. You'll likely want to create the new access record and then revoke the outdated one.
  • Alternatively, on the page below, you can see and edit the role and expiry information of active keys only.
    
    • Navigate to: Menu > Access > Access Groups > group name > Users > select key
• Revoke
  • This is a permanent action which can show differently depending on the page you are on.
  • On the main page, if access is revoked, the record will remain in your list with an X icon.
  • If you wish to reinstate that access you'll need to create a new key, etc.

#3 Provide Documentation

Last, you'll assemble and send the information below to your development team so they can finish this setup process in the final section below.

1. Securely provide your API key.
2. Provide this page's link for the Developer instructions below.
3. Provide the API Documentation link from the page below.
   1. Navigate to: Athennian > user details > Settings > API Documentation (screenshot below)
4. If you have not already, provide them at least one example of the simplest access you are providing so they know how to test and confirm that the initial setup is successful.

Optional Considerations:

• Documentation
  • This will be used in the developer instructions below.
  • Examples:
    • Production: name.athennian.com/API_docs/index.html
    • Sandbox: name.test.athennian.com/API_docs/index.html

API Developers:

Below you'll find the remaining 2 steps for setting up your API! These are done by your development team. Optional considerations listed at the end of each section.

#4 Create Request

1. Receive the instructions from your Athennian Admin from the previous steps.
2. Open up Postman, Insomnia or similar API tool.
3. Create your query request and URL depending on if this setup is for a Sandbox or Production environment as shown below.
   
   1. To do this, confirm if the API Documentation (or environment) link includes the word "test". If it does, you are setting up a Sandbox environment. Please review the details for each type at the end of this section.
   2. In either case, this API Documentation link is the primary technical resource to learn how to use the API.
4. Set the Headers & Authentication:

   1. Content-Type: application/json

   2. x-api-key: (API key value provided)

Sandbox:

• In this case you can create 2 main types of requests: GraphQL or HTTP POST
  • Note: GraphQL generally allows you to more natively explore the schema, validations, etc.
• Referencing the documentation link, add your request URL by adding the keyword "api" as shown below:
  • Example: https://nameapi.test.athennian.com

Example:

Production:

• In this case you can create 2 main types of requests: GraphQL or HTTP POST
  • Recommendation: Use HTTP POST because production GraphQL will not provide native schema exploration, validations, etc.
  • All requests will be POST (even to get data).
• Add your request URL:

  • https://api.athennian.com

Example:

#5 Test Setup

Finally, you are ready to test your initial setup to confirm everything was done correctly!

1. To do this, add a simple, valid query to the Body of your request and click submit!

Optional Considerations:

• Success
  • Successful setups generally will return some kind of 200 OK response.
• Queries
  • The amount of tests and the contents of your requests depends on the nature of your integration. This should've been provided to you already by your team. For example, you might want to confirm you can both get and post data via the API.

Thank you for reading!