Skip to main content
Swagger
All documentation pages

Set Up Automatic API Authentication

To change these settings, you need the Designer or Owner role in your Swagger Studio organization, or the SmartBear Admin role.

Before you begin, deploy a webhook that verifies the Portal-Signature header and returns a token. See Webhook Request and Response.

To set up Automatic API Authentication:

  1. Navigate to the portal configuration page, and then select the Automatic API Authentication tab.
  2. Enter the URL of your webhook in the Webhook URL box.
  3. Click Generate Secret.
  4. Copy the secret and store it in a secrets manager or an environment variable. Note, Portal shows the secret only once.
  5. Turn on the Enable Automatic API Authentication toggle.
  6. Click Apply Changes.
  7. Review the changes in the confirmation dialog box, and then confirm.

Members get a token the next time they log in. Active sessions are not affected.

Webhook URL Requirements

Portal calls a URL only if it passes these checks. Portal runs them when you save and on every call:

  • The URL uses HTTPS and has no more than 500 characters.
  • The URL doesn’t contain credentials, such as https://user:pass@host.
  • The URL uses port 443, the default for HTTPS.
  • The host name resolves through DNS to a public IP address. Portal blocks private, loopback, link-local, cloud-metadata, and other reserved ranges, so it cannot reach a webhook on an internal network.
  • The webhook doesn’t redirect. Portal treats any 3xx response as a failure.

Portal connects only to the address that it checked.

If you change the URL to a different origin (scheme, host, or port), generate a new signing secret and apply it with the URL. Portal never reuses a secret across different servers. If you change only the path, the current secret stays valid.

Signing Secret

Portal signs every webhook call with a signing secret. Your webhook uses its own copy of the secret to confirm that a request came from Portal.

  • Portal shows the secret only when you click Generate Secret. You cannot retrieve it later.
  • A new secret takes effect only after you click Apply Changes. If you regenerate the secret, the current one keeps working until you apply the new one.
  • A generated secret expires after 30 minutes if you do not apply it. Generate a new one.
  • After you apply a new secret, Portal signs requests with it immediately. Update your webhook to accept the new secret when you apply it.

Was this page helpful?