SecurityScheme for API that requires API key in custom header?


#1

I’m trying to create a simple RAML file describing a Mashape API that requires you to authenticate through an API key in the header. I’m creating this RAML file as a demo for comparing different API tools.

I can’'t see how to define the right security scheme using the RAML spec. My sample API requires authentication by adding X-Mashape-Key: “123” in the header, where 123 is the authentication key. How can I represent this in the security scheme in the RAML spec?

Here’s my RAML file so far:

#%RAML 0.8
---
title: Mashape Weather API
baseUri: https://simple-weather.p.mashape.com
version: v1

/aqi:
  get: 
    headers:
      x-mashape-key: 
        displayName: Mashape key
        description: This header is used to send data that contains your mashape API key
        type: string

    description: Get the air quality index (AQI). The AQI number indicates the level of pollution in the air. **Higher** numbers are worse.
    queryParameters:
      lat:
        displayName: Latitude
        description: The latitude coordinate
        type: number
        required: true
        example: 37.354108
      lng:
        type: number
        description: The longitude coordinate
        required: true
        example: -121.955236
    responses:
       200:
         body:
           application/text:
            example: |
               65

It works if I put the header on each endpoint, but I feel like that is redundant and not the right way to write it.


#2

I think you can use describedBy :

securitySchemes:
    - mashapeKey:
     type: x-mashape-key
     describedBy:
       headers:
         X-Mashape-Key:
           pattern: your-pattern

#3

Thanks redben. I tried that, but it makes it so the console doesn’t return any responses.


#4

The documentation for the security schemes needs to provide more detail for integrating custom headers. The existing doc is heavily weighted towards integration with OAuth, but not if you just need to integrate a custom key in a header. Wish the spec were clearer…