Authentication and API Key Management

Securing your interactions with the Document Summarization API is paramount. This guide provides detailed instructions on how to authenticate your API requests using subscription keys, manage these keys through the Developer Portal, and ensure your integrations remain secure.

• How to Obtain Your Subscription Key

  1. Sign In to the Developer Portal

     • Visit the Developer Portal at [Your Dev Portal URL].
     • Click on the "Sign In" button and log in using your Azure account credentials. If you're new to Azure, create an account here.

  2. Navigate to the API Section

     • Once logged in, go to the "APIs" tab in the navigation menu.
     • Locate the Document Summarization API from the list of available APIs.

  3. Access Subscription Keys

     • Click on the Document Summarization API to view its details.
     • In the API dashboard, find the "Subscription Keys" section.
     • Here, you'll see one or more subscription keys. These keys are unique to your account and are used to authenticate your API requests.

  4. Copy Your Subscription Key

     • Click on the "Copy" button next to the desired key to copy it to your clipboard.
     • Store your subscription keys securely; treat them like passwords.

• Securing Your Subscription Key

  • Never Share Your Keys Publicly: Ensure your subscription keys are not exposed in client-side code, public repositories, or shared in unsecured channels.
  • Use Environment Variables: Store keys in environment variables or secure storage solutions within your applications.
  • Rotate Keys Regularly: Periodically regenerate your subscription keys to minimize security risks.
  • Monitor Usage: Keep an eye on your API usage metrics in the Developer Portal to detect any unusual activity that might indicate compromised keys.

• Using Subscription Keys in Requests

  • Authorization Header:

    Include your subscription key in the Ocp-Apim-Subscription-Key header of your HTTP requests. Here's an example using cURL:

    bashCopy codecurl -X POST "https://api.yourdomain.com/document/summarize" \ -H "Content-Type: application/json" \ -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \ -d '{ "text": "Your document text here.", "format": "bullet_points", "model": "standard" }'

  • Query Parameter (if applicable):

    Alternatively, you can pass the subscription key as a query parameter:

    bashCopy codecurl -X POST "https://api.yourdomain.com/document/summarize?subscription-key=YOUR_SUBSCRIPTION_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "Your document text here.", "format": "bullet_points", "model": "standard" }'

    Note: Using the Authorization header is recommended for better security.

• Managing Subscription Keys

  • Viewing Keys:

    In the Developer Portal, under the Document Summarization API, navigate to the "Subscription Keys" section to view all available keys.

  • Regenerating Keys:

    If you suspect a key has been compromised or wish to rotate your keys for security reasons:

    1. Click on the "Regenerate" button next to the key you wish to rotate.
    2. Confirm the regeneration process. The old key will be invalidated, and a new key will be generated.
    3. Update your applications with the new key to ensure continued access.

  • Revoking Keys:

    To completely disable a subscription key:

    1. In the "Subscription Keys" section, locate the key you wish to revoke.
    2. Click on the "Revoke" or "Delete" button associated with that key.
    3. Confirm the revocation. The key will no longer be valid for API requests.

• Best Practices for API Key Management

  • Least Privilege: Assign keys with the minimal necessary permissions required for your applications.
  • Secure Storage: Use encrypted storage solutions or key management services to store your keys.
  • Access Controls: Limit access to subscription keys to only those team members or systems that absolutely need them.
  • Regular Audits: Periodically review your subscription keys and their usage to ensure compliance with your security policies.

With your subscription key obtained and secured, proceed to the next article, "Making Your First API Request," to learn how to utilize the Document Summarization API effectively.