# Create the API OAuth key

> Create the Canvas API OAuth Developer Key with the exact application and administrator scopes, and handle scopes that do not appear in the UI.

[Canonical HTML page](https://safeonlineexam.com/docs/canvas/api-oauth-key)

The application uses **user-scoped Canvas OAuth tokens** for assessment discovery
and access-code changes. This is separate from the LTI key, and it is not a
personal access token — do not substitute one.

<Steps>
  <Step>
    ### Create the key with the callback [#create-the-key-with-the-callback]

    In the **root account's** Developer Keys area, create an **API** key with this
    redirect URI:

    ```text
    ${TOOL_URL}/api/oauth2callback
    ```
  </Step>

  <Step>
    ### Add the application scope set [#add-the-application-scope-set]

    If your Canvas enforces scopes, allow this complete application scope set:

    ```text
    url:GET|/api/v1/courses
    url:GET|/api/v1/courses/:course_id/quizzes
    url:GET|/api/v1/courses/:course_id/assignments
    url:GET|/api/quiz/v1/courses/:course_id/quizzes/:assignment_id
    url:PUT|/api/v1/courses/:course_id/quizzes/:id
    url:PATCH|/api/quiz/v1/courses/:course_id/quizzes/:assignment_id
    url:GET|/api/v1/login/session_token
    ```

    <Callout title="Why every connection requests the same scopes">
      Every Canvas connection requests this same set, regardless of the user's role in
      the course that started authorization. This prevents someone who is an instructor
      in one course and a student in another from keeping an incompatible role-specific
      grant. Canvas still enforces the user's actual account and course permissions.
      The course-list scope powers the instructor's **Duplicate to courses** picker; the
      service requests only active teacher courses and rechecks that list immediately
      before copying a tool.
    </Callout>
  </Step>

  <Step>
    ### Add the administrator scope set [#add-the-administrator-scope-set]

    For the root-account administrator dashboard, also allow this administrator scope
    set on the **same** OAuth key:

    ```text
    url:GET|/api/v1/accounts/:id
    url:GET|/api/v1/accounts/:account_id/permissions
    url:GET|/api/v1/accounts/:account_id/courses
    url:GET|/api/v1/accounts/:account_id/terms
    url:GET|/api/v1/courses/:id
    url:GET|/api/v1/courses/:course_id/quizzes/:id
    ```

    Administrator authorization requests the complete application set — including
    `url:GET|/api/v1/login/session_token` — **plus** these administrator scopes.
    Account and term collection access powers the paginated active-course picker; it
    does not import the account's full historical catalog. One OAuth grant is stored
    per Canvas user; administrator consent upgrades that grant in place, and later
    instructor/student reauthorization preserves the administrator scope profile. A
    multi-role administrator therefore authorizes once and reuses the same refreshable
    grant everywhere.

    The individual Classic Quiz read scope lets a root administrator snapshot current
    Canvas access codes before a course reset changes anything. It is an
    administrator-only capability; ordinary instructor and student OAuth contracts do
    not change.
  </Step>

  <Step>
    ### Store the client ID and secret [#store-the-client-id-and-secret]

    Store the key's client ID and secret in your secret store as
    `CANVAS_API_CLIENT_ID` and `CANVAS_API_CLIENT_SECRET`.
  </Step>
</Steps>

## When a scope does not appear in the UI [#when-a-scope-does-not-appear-in-the-ui]

Some Canvas environments do not show every endpoint scope in the Developer Keys
UI. This most often bites the `session_token` scope.

<Callout type="warn" title="Do not substitute a similar-looking permission">
  Do **not** replace `url:GET|/api/v1/login/session_token` with a similarly named
  login permission. Use the instance's supported Developer Keys administration/API
  path to add the exact endpoint scope, deploy the service, then have each affected
  administrator select **Reconnect Canvas** once.
</Callout>

Administrator-only scope additions do not invalidate ordinary instructor or
student connections, and scope changes apply only to newly issued tokens. If you
change the redirect URI or the scope set, affected users must reauthorize. The
symptom-driven version of this is in
[Troubleshooting → OAuth & scopes](/docs/troubleshooting/oauth-scopes).

Grants from before scope-contract version 3 do not include the course-list scope.
Have affected instructors select **Reconnect Canvas** before using the
course-to-course tool-copy feature.

Next: [Create the LTI 1.3 key](/docs/canvas/lti-key).