Retrieving an access token is a multi-step process that will enable you to perform actions on behalf of a user. Nearly all API resources require an access token.
Resources referenced:
authorization_code: a secret code that is valid for 1 year. Required to obtain an access_token.
access_token: a secret token that allows you to perform actions on behalf of a user. Valid for 30 minutes.
Developer API documentation: HorizonWebRef Developer API documentation
Here are the basic steps to start performing API calls:
Obtain a temporary special use login url via the /oauth2/requestCode resource.
Direct the end user to the temporary login_uri location that is returned from the /oauth2/requestCode endpoint via a pop-up window (or iFrame, but we recommend a pop-up window).
Once the end user has authorized your application to access their account, the end user will be redirected to your callback_uri that you specified in Step #1. A query (GET) parameter will be added to the end of your callback_uri containing one or more authorization_codes. Each authorization_code corresponds to a unique affiliation they have within the system. If multiple authorization_codes are issued, the authorization_codes query parameter will be comma separated.
Securely store and save the authorization_codes. These codes are valid for 1 year and will be required to continue to access the user's account without needing to login again until the codes have expired (1 year).
When you're ready to make an API call on behalf of the user, use the /oauth2/requestToken resource to exchange the authorization_code for an access_token. Access tokens are valid for 30 minutes. When an access token has expired, you will need to obtain a new access_token using the same authorization_code from Step #3 using the /oauth2/requestToken resource.
Securely and temporarily store the access_token and complete your desired API calls using the new token.
After your authorization_code has expired (1 year), you'll need to start over again from Step #1 to continue acting on behalf of the user.
More than one organization
If the signed-in member belongs to more than one organization, the approval screen can list each organization that can grant at least one requested scope. The member can uncheck an organization, or uncheck individual scopes, before choosing Accept. That is how authorization is limited to one organization. The requestCode resource cannot pre-select a single organization.
After Accept, you receive one authorization code per accepted organization. Exchange and store each code separately. Later /schedule calls act on the organization that belongs to the access token you send.
See What developer scopes are available? for which membership roles can grant each scope, and which scopes /schedule needs to add, update, cancel, or delete events.
If the approval page cannot continue
If none of the member's organizations can grant any requested scope, the approval page says: This developer wants permissions that you don't currently have. You won't be able to complete this, sorry. Ask an organization administrator to confirm the member is an assignor or organization administrator in the organization the app needs to change. Developer API plan tiers do not turn organization write scopes on or off.
Authorization cannot be completed while an administrator is simulating another account. Exit simulation first, then open the login_uri again.
Authorized apps can later be revoked from Personal Profile.
API Authorization Page:
