title: REST Authentication: put key in custom header or Authorization header?
body: <p>I'm designing a REST API framework for a large security-conscious company.</p>
  
  <p>Every caller to our services needs to provide a client key to access the system. We will use that for authorizing access for that particular client as well as rate limiting and monitoring. Also <em>some</em> of our API calls will access customer data, and we will use OAuth 2 tokens to control access to that data.</p>
  
  <p>My question is how to pass the client key. I can not use HTTP Basic Authentication or a query parameter because we cannot pass it in the URI (URIs get logged sometimes) -- it must be in an HTTP header instead. So I have thought of two approaches, both with flaws:</p>
  
  <p>(1) Invent our own header: <code>MyCompanyAPIKey: api-key-goes-here</code>. This is flawed because we will be inventing our own header and that's a poor design choice. It won't work with anyone else or with standard tools (because we invented our own).</p>
  
  <p>(2) Use the Authorization header: <code>Authorization: Bearer api-key-goes-here</code>. This is flawed because it will conflict with OAuth (which needs that header) in the cases where we use that. Technically I suppose we don't <em>need</em> the client key when we have an OAuth token (since the OAuth token was specific to a single client), but I don't know if the normal tools can handle that.</p>
  
  <p>How do you think we should proceed?</p>