Verzoeken autoriseren in de Try It!-console

Try It! laat ontwikkelaars hun verzoeken direct in de console authenticeren, met het beveiligingsschema dat jouw API definieert. Document360 leest de authenticatieconfiguratie uit je OpenAPI-specificatie en toont de juiste velden voor elke methode, zodat ontwikkelaars inloggegevens kunnen opgeven en een geautoriseerd verzoek kunnen sturen zonder de documentatie te verlaten.

Dit artikel legt uit hoe je een authenticatiemethode kiest in de console, hoe elke ondersteunde methode werkt, en hoe je je OpenAPI-specificatie configureert zodat de methode correct verschijnt in Try It!. Voor een algemeen overzicht van de console, zie Testen van eindpunten met Try it!.

Het kiezen van een authenticatiemethode

Wanneer een endpoint één of meer beveiligingsschema's definieert, toont de Try It!-console een tabblad Autorisatie . Bovenaan dat tabblad staat een Authenticatiemethodeselector met alle schema's die het eindpunt ondersteunt.

Selecteer een methode en de console toont de inlogvelden voor dat schema. Als een endpoint meer dan één methode ondersteunt, kunnen ontwikkelaars kiezen waarmee ze willen authenticeren.

Document360 ondersteunt de volgende authenticatiemethoden:

Authenticatiemethoden worden gedefinieerd in je OpenAPI-specificatie onder components/securitySchemes en toegepast op individuele eindpunten met behulp van het security veld.

API-sleutel

API-sleutelauthenticatie gebruikt een unieke sleutel die in de requestheaders wordt doorgegeven.

In je OpenAPI-specificatie:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

Pas het toe op een eindpunt:

/your-endpoint:
  get:
    security:
      - ApiKeyAuth: []

Selecteer in de console de API-sleutel als authenticatiemethode. Het Naam-veld is vastgelegd aan de headernaam die in je specificatie is gedefinieerd (X-API-Key in het bovenstaande voorbeeld), en ontwikkelaars voeren hun sleutel in het Waarde-veld . De sleutel wordt vervolgens in die header gestuurd met het verzoek.

Basisauthenticatie

Basisauthenticatie vereist een gebruikersnaam en wachtwoord die worden gecodeerd en doorgegeven in de Authorization header van elk verzoek.

In je OpenAPI-specificatie:

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

Pas het toe op een eindpunt:

/your-endpoint:
  get:
    security:
      - basicAuth: []

Selecteer in de console Basisauthenticatie en voer de gebruikersnaam en het wachtwoord in. Try It! codeert ze en stuurt ze in de Authorization header wanneer het verzoek wordt verzonden.

Dragertoken

Bearer-tokenauthenticatie gebruikt een token dat in de Authorization header wordt doorgegeven als Bearer <token>.

In je OpenAPI-specificatie:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

Pas het toe op een eindpunt:

/your-endpoint:
  get:
    security:
      - BearerAuth: []

Selecteer in de console Bearer-token en voer de token in. Probeer het! stuurt het in de Authorization header als Bearer <token>.

OAuth 2.0

OAuth 2.0 laat ontwikkelaars autoriseren via een aanmeldingsstroom in plaats van een statisch inlogificatieformulier in te voeren. Document360 ondersteunt de volgende flows — gebruik degene die overeenkomt met hoe je API toegangstokens uitgeeft.

Aanmelden

Wanneer een ontwikkelaar OAuth 2.0 selecteert in de console, ziet hij de configuratie van het schema en een lijst met scopes, gevolgd door een knop Autoriseren . De scopes die voor het schema zijn gedefinieerd, zijn vooraf geselecteerd; Ontwikkelaars kunnen alle die ze niet nodig hebben opklaren voordat ze toestemming geven.

Door op Autoriseren te klikken start je de aanmeldstroom. Wanneer de API PKCE gebruikt, is er geen handmatige configuratie nodig in de console — Try It! regelt de exchange automatisch, en de ontwikkelaar hoeft alleen maar in te loggen. Zodra de autorisatie is voltooid, gebruikt de console het resulterende toegangstoken voor verzoeken naar dat eindpunt.

Voorbeeld specificatiedefinitie (Autorisatiecodeflow)

components:
  securitySchemes:
    oauth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.yourdomain.com/oauth/authorize
          tokenUrl: https://auth.yourdomain.com/oauth/token
          scopes:
            read: Read access
            write: Write access

Voor het redirect-URI- en tokenverversingsgedrag dat OAuth 2.0 vereist, zie hieronder het Configureren van uw OAuth-provider .

OpenID Connect

OpenID Connect breidt OAuth 2.0 uit door gebruikersidentiteitsverificatie toe te voegen. Het is geconfigureerd vergelijkbaar met OAuth 2.0 en heeft dezelfde redirect-URI- en stille vernieuwingsvereisten.

In je OpenAPI-specificatie:

components:
  securitySchemes:
    openIdConnect:
      type: openIdConnect
      openIdConnectUrl: https://auth.yourdomain.com/.well-known/openid-configuration

Selecteer OpenID Connect in de console en voltooi de aanmeldflow. Net als bij OAuth 2.0, zie hieronder de vereiste providerinstellingen Configureren van uw OAuth-provider .

Je OAuth-provider configureren

Zowel OAuth 2.0 als OpenID Connect vereisen twee instellingen zodat autorisatie correct werkt in Try It!.

Redirect URI — Nadat een ontwikkelaar de autorisatieflow heeft voltooid, stuurt de provider hen terug naar de API-referentie. Voeg de OAuth-callback-URL van de API-referentie toe aan de lijst van toegestane redirect-URI's van je OAuth-provider:

https://<your-knowledge-base-domain>/assets/apidocs-oauth-callback.html

Vervang <your-knowledge-base-domain> het door het domein waarop je API-documentatie is gepubliceerd.

Stille verlenging — Document360 ververst automatisch het toegangstoken op de achtergrond terwijl een ontwikkelaar actief Probeert het! gebruikt, zodat de sessie niet halverwege gebruik verloopt. Er is geen configuratie nodig aan jouw kant; dit wordt automatisch afgehandeld.

Meerdere beveiligingsschema's toepassen op één eindpunt

Als een eindpunt meer dan één authenticatiemethode tegelijk vereist, definieer deze dan samen onder op security het operationele niveau:

/secure-endpoint:
  get:
    security:
      - BearerAuth: []
        ApiKeyAuth: []

Dit vereist zowel een Bearer-token als een API-sleutel voordat het verzoek kan worden verzonden. Try It! ondersteunt meerdere beveiligingsschema's in één sessie, zodat ontwikkelaars voor elk gegevens kunnen opgeven en één geautoriseerd verzoek kunnen sturen.

Sessies en beveiliging

• Credentials zijn alleen voor sessies. De inloggegevens die een ontwikkelaar invoert, worden alleen bewaard voor de actieve sessie en worden niet opgeslagen. Wanneer de sessie eindigt, moeten ze opnieuw worden ingevoerd.
• Inloggegevens worden gemaskeerd in de verzoekpreview. Gevoelige waarden zijn verborgen in de Request-preview zodat ze niet op het scherm worden getoond tijdens het opbouwen van een request.

FAQ