The Basic Authentication policy type enables you to use the lightweight Basic Authentication for last-mile security. The policy takes the username and password defined in the policy, Base64 encodes them, and adds the resulting value to the Authorization: Basic HTTP header. The policy gets the username and password from variables that you define. The username and password are commonly stored the key/value store and then read from the key/value store at runtime. For details on using key/value store, see Persist data using KeyValueMap.

The policy also lets you decode basic authorization credentials on an inbound request.

Basic authentication does not provide confidentiality. Always send credentials over a TLS-enabled (HTTPS) connection to your backend service.


The following samples illustrate how you can use the Basic Authentication policy to encode and decode basic auth credentials.

Outbound encoding

In the configuration below, username and password are from the variables specified in the ref attributes on the User and Password elements. The variables must be set by another policy before this policy executes. Typically, the variables are populated by values that are read from a key/value map. (See Persist data using KeyValueMap).

<BasicAuthentication name="ApplyBasicAuthHeader">
  <User ref="BasicAuth.credentials.username" />
  <Password ref="BasicAuth.credentials.password" />
  <AssignTo createNew="false">request.header.Authorization</AssignTo>

This configuration results in an Authorization HTTP header being applied to the outbound request message. (The outbound request is the message that the API proxy sends to the backend service specified in the TargetEndpoint configuration). User and Password are concatenated with a colon prior to Base64 encoding.

Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk

Imagine that you have a key/value map with the following entry:

  "entry" : [ {
    "name" : "username",
    "value" : "MyUsername
  }, {
    "name" : "password",
    "value" : "MyPassword
  } ],
  "name" : "BasicAuthCredentials"

Then you would attach the following KeyValueMapOperations policies before the BasicAuthentication policy. This way, the values for username and password are extracted from the key/value store and populated into the variables BasicAuth.credentials.username and BasicAuth.credentials.password.

<KeyValueMapOperations name="getUsername" mapIdentifier="BasicAuthCredentials">
  <Get assignTo="credentials.username" index='1'>
      <Parameter ref="BasicAuth.credentials.username"/> 
<KeyValueMapOperations name="getPassword" mapIdentifier="BasicAuthCredentials">
  <Get assignTo="credentials.password" index='1'>
      <Parameter ref="BasicAuth.credentials.password"/> 

Inbound decoding

The Basic Authentication policy type also supports decoding Authorization: Basic HTTP headers on inbound requests.

<BasicAuthentication name="DecodeBaseAuthHeaders">
  <DisplayName>Decode Basic Authentication Header</DisplayName>
  <User ref="request.header.username" />
  <Password ref="request.header.password" />

Configuring the BasicAuthentication policy

Configure BasicAuthentication using the following elements.

Field Name Description Default Required
name The unique name of the policy. Use this name to reference the policy within a Step definition element. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.


N/A Yes
DisplayName A friendly name for the policy, which is displayed in the management UI. N/A Yes

Supports valid values Encode and Decode. This setting determines whether the policy will Base64 encode credentials to populate an Authorization: Basic HTTP header on an outbound request, or whether it will decode Base64-encoded credentials from an Authorization: Basic HTTP header on an inbound request.

N/A Yes

Supports valid values true or false. When set to true, the policy will not throw an error if a variable cannot be resolved. When used in the context of a BasicAuthentication policy, this setting is usually set to false, because it is generally beneficial to throw an error if a username or password cannot be found in the variables specified.

N/A Yes
User and ref

Settings for username.

For encoding, set the username with a reference attribute to dynamically retrieve the username from a variable. User and password are concatenated with a colon prior to Base64 encoding. If you store credentials in a key/value map, this variable will be the one to which the GET operation assigns the value of the username. See Persist data using KeyValueMap

For decoding, specify the flow variable in which the decoded username is to be placed.




The variable from which the policy dynamically reads the username. .

N/A Yes
Password and ref

Settings for password.

For encoding, set the password with a reference attribute to dynamically retrieve the password from a variable. The best practice is to store passwords in a key/value map and retrieve them dynamically at runtime. If you store credentials in a key/value map, this variable will be the one to which the GET operation assigns the value of the password. See Persist data using KeyValueMap.




The variable from which the policy dynamically reads the password. .

N/A Yes

For encoding, the location where the Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk is set. If you don't specify AssignTo, the request.header.Authorization is used.

For BasicAuthentication, you will usually set the attribute createNew to false. The reason is that you do not require the policy to generate a new message. Instead, you require the HTTP Authorization header to be added to the existing request message.

N/A Yes

For decoding, the location of the Authorization: Basic TXlVc2VybmFtZTpNeVBhc3N3b3Jk. The decoded credentials must contain user and password strings concatenated by a colon. If you don't specify Source, the value is taken from request.header.Authorization.

N/A Yes

Policy-specific variables

No variables are set by this policy.

Policy-specific error codes

The error code is thrown under the following conditions:

  • When IgnoreUnresolvedVariables is false and the source for the decode or encode is not present
  • When a Basic Authentication HTTP header is not present on an inbound request
Error Code Message
InvalidBasicAuthenticationSource Source variable : request.header.Authorization for basic authentication decode policy is not valid

Policy schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)