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:
- Navigate to the portal configuration page, and then select the Automatic API Authentication tab.
- Enter the URL of your webhook in the Webhook URL box.
- Click Generate Secret.
- Copy the secret and store it in a secrets manager or an environment variable. Note, Portal shows the secret only once.
- Turn on the Enable Automatic API Authentication toggle.
- Click Apply Changes.
- 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.