# Authentication

Authentication against our API is made using the OpenID Connect (OIDC) standard.

# The OIDC standard

We recommend you familiarize yourself with the OIDC standard/specification, or use some library that implements it for your language of choice. The OpenID foundation maintains a very comprehensive specification for OIDC, alongside a list of certified tools and libraries.

# OIDC and easyroam

Once you have familiarized yourself with OIDC, you will want to register your OIDC client on our end. For simplicity we will refer to OIDC clients as API clients although they are basically OIDC clients.

We offer two types of API clients, based on the usecase.

easyroam services operate outside of the user context and therefore use the client_credentials flow to obtain an access_token.

Warning

easyroam services come with administrator permissions. Under no circumstances should you ever give away any credentials associated with an easyroam service.

easyroam services are intended for use as a background service and should not be used in combination with a frontend for users.

Find out more in easyroam services

easyroam useragents use the authorization_code flow. This essentially means, that it requires an end user to browse to an authentication url on https://auth.easyroam.de, and then be redirected to the client at a predetermined url.

easyroam useragents are intended for use in combination with a frontend for users (e.g. a realm specific app).

Find out more in easyroam useragents

Every client is registered to the realm the creator belongs to, not to the account of the creator. This means other administrators that belong to your realm can see, edit and delete your clients.

# Scopes

The easyroam API uses scopes as means to control access to API endpoints for different clients. They also serve as as an additional tool for developers to limit which endpoints their applications should be able to access. Further the user has the possibility to approve the access the API client requested on their behalf.
Some scopes still require administrator privileges on the user level to be used and are marked with Admin only .
Some scopes shouldn't be used by services because they rely on a user context and are marked with No service .
The following table lists scopes and their respective permissions:

Scope	Description
`openid`	Indicates that the API client intends to use OIDC to verify the user's identity. The server will return an `id_token` on successful authentication. No service
`offline_access`	Indicates that the API client intends to use a `refresh_token` to request a new `access_token`. No service
`audit.read`	Allows the API client to read the audit log. Admin only
`auth.clients.create`	Allows the API client to create new API clients on the authentication server. Admin only
`auth.clients.delete`	Allows the API client to delete existing API clients from the authentication server. Admin only
`auth.clients.read`	Allows the API client to request a list of all API clients from the authentication server. Admin only
`auth.clients.delete`	Allows the API client to delete API clients. Admin only
`auth.sessions.delete`	Allows the API client to revoke active sessions on the authentication server. No service
`auth.sessions.read`	Allows the API client to request a list of active user sessions from the authentication server. No service
`profile.create`	Allows the API client to create new profiles for the current user No service
`profile.delete`	Allows the API client to revoke profiles for the current user No service
`profile.modify`	Allows the API client to modify the existing profiles of the current user. No service
`profile.read`	Allows the API client to request a list of active profiles for the current user. No service
`realm.read`	Allows the API client to request the current settings of their realm.
`realm.update`	Allows the API client to modify the current realm settings. Admin only
`user.modify`	Allows the API client to modify accounts of all users in their realm. Admin only
`user.profile.create`	Allows the API client create new profiles for users in their realm. Admin only
`user.profile.delete`	Allows the API client to revoke existing profiles for users in their realm. Admin only
`user.profile.read`	Allows the API client to request a list of all active profiles in their realm. Admin only
`user.read`	Allows the API client to request a list of all users in their realm Admin only
`user.delete`	Allows the API client to delete users in their realm. Admin only
`user.undelete`	Allows the API client to reactivate users in their realm. Admin only
`audit.read`	Allows the API client to read you realms audit logs. Admin only

# Using the authorization_token to access the API

Once you have obtained an access_token you can use it to access the API. The easyroam API uses the Bearer authentication scheme. This means you need to add an Authorization header to your request like so:

Authorization: Bearer <your_access_token>

If you are using a library to access the API, it will most likely have a method to set the Authorization header for you.