Summary

Below you'll find a summary of how to setup API Access.

The 4 main steps are in 2 categories:

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

Prerequisites

• Access
  • Before starting each API integration project, please confirm that your account has the appropriate API Tier turned on with your Athennian representative. Changes to the API Tier may necessitate all new keys to be generated for any existing integrations development.
  • This is also a good time to confirm your API URL, and any other collaborations that may help. If appropriate, an APi implementation ticket will be created for any relevant communications.
• Development
  • You will need your API integration developer for the last part of this setup. If preferred, you can add them as Admin users and provide any additional instructions so they can manage their own API keys, access groups, etc.

Athennian Admins:

Below you'll find the first 2 steps for setting up your API. These are done by one of your Athennian Administrators (more access) or Office-Admins (less access).

#1 Create Key

This step is like creating a user without any access. If you need to change your API Tier at any time, new keys may need to be created.

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 (this will only be shown once per key).

Optional Considerations:

• Groups
  • API roles etc mostly act just like non-API, but will soon be even better after the following are live: #HOOT-8473 ticket, and the API Tier read-only flag.
  • 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.
• Sharing
  • If you need to send your key in an message, consider including it separately in a follow-up message. This will allow you to track and document each initial thread while sharing the key less.
•  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)

If desired, here you can change application and data access to the new key over time.

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.

API Developers:

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

#3 Create Request

The instructions below cover the bulk of our API which is GraphQL. REST portions of the API will vary in some ways.

• Receive the instructions from your Athennian Admin from the previous steps for the key, API URL, and other relevant documentation.
• Open up Postman, Insomnia or similar API tool.
• Create HTTP POST request (even to GET data).
  • Include a GraphQL or JSON Body query or mutation as the one below or others here:
    
    • query {accessGroups{id}}
• Add your request API URL.
• Set the Headers & Authentication:

  1. Content-Type: application/json

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

Postman HTTP POST Example:

#4 Test Setup

You are now ready to test your initial setup to confirm everything was done correctly (click Send).

Optional Considerations:

• Success
  • Successful setups generally will return some kind of 200 OK response. However, GraphQL requires required additional validate in the response as you can have partial successes.
• 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 import and export certain data via the API.