# Inspire360 REST API Documentation * [LayerLMS / V4](https://inspire360.stoplight.io/docs/layerlms) * [Legacy / V3](https://docs.inspire360.com/api/v3) > #### Domains > > In this document, many references may be made to ``, such as `https:///login`, for instance. > This is a reference to your domain on our site. This may be `https://.inspire360.com`, or it may be a custom domain, if you have one set up. If you *do* have a custom domain, and do not know what you `` is, you can request `https:///v4/sites/me` (no authentication required) to obtain your site details - your `` is returned as the `identity` field in the response. > #### UAT Domain > > We have a UAT environment that may be used with our API for testing. For this, the domain will always be: > `.uat.inspire360.tech` ## Server URL Your site's server URL is used for all API endpoints. Please note that the URLs specified in this documentation are _mock_ URLs only, and may be used for integration, but will need to be replaced with your actual Inspire360 domain. The _mock_ URL you will see here is:`https://stoplight.io/mocks/inspire360/layerlms/602056164` - to replace that, you would use `.inspire360.com` instead (unless you have a custom domain, in which case the custom domain would be used). Additionally, you may use `.uat.inspire360.tech` for testing purposes. Please inform us ahead of time if you would like to do so, as we may need to set up your credentials here as well as on production. ## Authentication In order to use protected endpoints, you will need a token associated to an account with the appropriate role(s). You would then use this token as a "bearer" token for each request. For example: ```bash curl --header "authorization: bearer " \ https:///v4/accounts/me ``` If you do not yet have an account with the appropriate roles, please contact us. ### Authenticating with Inspire360 If Inspire360 is your IDP (Identity Provider), you will need to be set up with a `clientId` and `secret`, and use the `client_credentials` grant type. Upon request, we will create a client for you on our IDP, and give you the authentication URL, clientId and secret. Once you have this information, you can create a token with the following request: ```bash curl --request POST \ --header "Content-Type: application/x-www-form-urlencoded" \ --header "Accept: application/json" \ --data "client_id=&client_secret=&grant_type=client_credentials" \ https://account.inspire360.com/realms//protocol/openid-connect/token ``` The resulting `json` will look something like this: ```json { "access_token": "", "expires_in": 60, "refresh_expires_in": 0, "token_type": "Bearer", "not-before-policy": 0, "scope": "profile email" } ``` Your requests against our endpoints would use the `access_token` supplied in the result, as specified above. ### Authenticating with another IDP If your site uses your own IDP (Identity Provider), you will need to obtain a token with your own process. Unless you have a custom setup, this token should be a JWT containing the following information in the claims: * first name * last name * email * user ID (user's unique identifier from your IDP) Alternatively, the discovery endpoint should have a `userinfo_endpoint` that returns the same. If so, assure that the scopes specified include those necessary to call this endpoint. The specific names for these fields may be custom with your specific SSO setup. ## Site Authentication Options (for all users) There are a few options you have when setting up authentication with our services. * Use our IDP * Use your own IDP * Offer a primary and one or more secondary IDP option(s) (see Multiple Providers block below) > #### Multiple Providers > > You may have multiple providers. This could take a few forms, and is a slightly more complex subject. If you are interested in knowing more, please set up a call with us and we will be happy to walk through the options. ### Use our IDP No additional setup is required on your end. Just let us know, and we'll set everything up. However, if you would like to use our IDP to authenticate users elsewhere, you may request a `client_id` and `secret` from us to use as part of your authentication flow. ### Use your own IDP In order to use your own IDP, you may either: * Use OpenID Connect (oidc) / Oauth2, or * Create a custom integration (integration fees may apply) If using `oidc`, you will need to create a `client_id` and `secret` for us to use for token exchange. The resulting JWT claims should contain the following data: Data | Default name | type ---------|----------|---------- First name | given_name | string, optional Last name | family_name | string, optional Email Verified | email_verified | boolean, optional Email | email | string, required User ID | sub | string, required (but _may_ be "email") > #### A note on using "email" as the user ID > > This is _not_ advised if the user has an option of changing the email address within the IDP, as this would "break" the association of the two accounts #### Setting up an external Identity Provider (IDP) In creating an endpoint, we use a UUID to identify the specific client setup. You could request the list of URLs with a pre-generated UUID from us, or you can create a UUID yourself (using any number of tools available to do so, such as `uuidgen` in mac, windows, or linux. With this, the token URLs we would like are: url | purpose ---------|---------- `https:///auth//token` | Production site `https://.uat.inspire360.tech/auth//token` | UAT site `https://.mp.inspire360.tech/auth//token` | QA site `https://.ja.inspire360.tech/auth//token` | Developer site `https://.dk.inspire360.tech/auth//token` | Developer site Send us (in a secure manor - secrets should not be sent via email, if avoidable): * Client UUID (if you generated a new one) * `client_id` * `client_secret` * Authorization URL and/or discovery URL * Account page URL (for directing users that would like to change their name and/or email address) * required scopes And, if not available in the discovery URL: * Public key or jwks endpoint * Token endpoint * logout / end session endpoint (when a user clicks the "logout" button on our site, they will be redirected to this location) ### Linking users to our site When linking users to our site, you can use `https:///login?redirect_uri=/path/to/resource` to assure that the user will be logged in. If they are already logged in via the IDP, this will automatically redirect the user to the specified resource. If a different user is logged into our site, this will log that user out and log the new user in. Additionally, you may use `https:///logout`