You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/reference/policies/access-entity-policy). info

![](https://docs.apigee.com/static/api-platform/images/icon_policy_mediation.jpg)

### What

Retrieves entity profiles you specify from the Apigee Edge data store. The policy places the
profile in a variable whose name follows the format `AccessEntity.{policy_name}`. You
can use `AccessEntity` to access profiles for the following entities:

- App
- API product
- Company
- Company developer
- Consumer key
- Developer

> [!NOTE]
> **Note:** Apigee Edge keeps the entities in cache for a minimum of 180 seconds after the entities are *accessed*.

The `AccessEntity` policy functions as a policy-based runtime database lookup. You
can use the profile information returned by this policy to enable dynamic behavior, such as
conditional endpoint routing, flow execution, policy enforcement.

You use the `AccessEntity` policy to get entity profile data **as
XML** and put it into a variable. You identify the entity to get by specifying an entity
type and one or more identifiers that specify which entity of that type you want. Later, in
another policy, you can retrieve the entity profile data with another policy, such as an
[ExtractVariables policy](https://docs.apigee.com/api-platform/reference/policies/extract-variables-policy) or [AssignMessage policy](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy).

> [!NOTE]
> **Note:** For examples of XML representing entity profiles, be sure to see "[Example entity profile XML](https://docs.apigee.com/api-platform/reference/policies/access-entity-policy#profiles)".

### Samples

The following samples show `AccessEntity` used in conjunction with the
`ExtractVariables` and `AssignMessage` policies to extract a developer's
email and add it to the HTTP header.

### Getting developer email for use in other policies

**Set up the `AccessEntity` policy to specify which entity profile to get from
Edge, as well as where to put the profile data.**

In the following example the policy gets a `developer` entity profile, using an
API key passed as a query param to identify the developer. The profile is placed in a
variable whose name follows the form `AccessEntity.{policy_name}`. So the variable
set by this policy would be `AccessEntity.GetDeveloperProfile`.

```
<AccessEntity name="GetDeveloperProfile">
  <!-- This is the type entity whose profile we need to pull from the Edge datastore. -->
  <EntityType  value="developer"/>
  <!-- We tell the policy to use the API key (presented as query parameter) to identify the developer. -->
  <EntityIdentifier ref="request.queryparam.apikey" type="consumerkey"/> 
</AccessEntity>
```

**Use another policy to retrieve the entity profile value from the variable set by
`AccessEntity`.**

In the following example, an `ExtractVariables` policy retrieves a value from
the `AccessEntity.GetDeveloperProfile` variable set earlier by
`AccessEntity`.

Note that the value retrieved is specified as an XPath expression in the
`XMLPayload` element. The extracted value is placed in a
`developer.email` variable.

```
<ExtractVariables name="SetDeveloperProfile">
  <!-- The source element points to the variable populated by AccessEntity policy. 
  The format is <policy-type>.<policy-name>.
  In this case, the variable contains the whole developer profile. -->
  <Source>AccessEntity.GetDeveloperProfile</Source> 
  <VariablePrefix>developer</VariablePrefix>
  <XMLPayload>
    <Variable name="email" type="string"> 
        <!-- You parse elements from the developer profile using XPath. -->
      <XPath>/Developer/Email</XPath>
    </Variable>
  </XMLPayload>
</ExtractVariables>
```

The following [AssignMessage policy](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy) retrieves the developer email set by the
[ExtractVariables policy](https://docs.apigee.com/api-platform/reference/policies/extract-variables-policy).

```
<!-- We'll use this policy to return the variables set in the developer profile, 
just so that we can easily see them in the response. -->
<AssignMessage name="EchoVariables">
  <AssignTo createNew="false" type="response"></AssignTo>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name="X-Developer-email">{developer.email}</Header>
    </Headers>
  </Set>
</AssignMessage>
```

*** ** * ** ***

## Element reference

The basic of structure of an `AccessEntity` policy is:

```
<AccessEntity name="policy_name">
  <EntityType  value="entity_type"/>
  <EntityIdentifier ref="entity_identifier" type="identifier_type"/> 
  <SecondaryIdentifier ref="secondary_identifier" type="identifier_type"/>
</AccessEntity>
```

You can access multiple entities of the same type by grouping them in an
`Identifiers` element:

```
<AccessEntity name="name_of_the_policy">
  <EntityType  value="type_of_entity"/>
  <Identifiers>
    <Identifier>
      <EntityIdentifier ref="reference_to_entity_identifier" type*="identifier_type"/> 
      <SecondaryIdentifier ref="reference_to_secondary_entity_identifier" type="identifier_type"/><!-- optional -->
    </Identifier >
    <Identifier>
      <EntityIdentifier ref="reference_to_entity_identifier" type*="identifier_type"/> 
      <SecondaryIdentifier ref="reference_to_secondary_entity_identifier" type="identifier_type"/><!-- optional -->
    </Identifier >
  </Identifiers>
</AccessEntity>
```

## \<AccessEntity\> attributes

```
<AccessEntity async="false" continueOnError="false" enabled="true" name="policy_name">
```

The following table describes attributes that are common to all policy parent elements:

| Attribute | Description | Default | Presence |
|---|---|---|---|
| `name` | The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name. | N/A | Required |
| `continueOnError` | Set to `false` to return an error when a policy fails. This is expected behavior for most policies. Set to `true` to have flow execution continue even after a policy fails. | false | Optional |
| `enabled` | Set to `true` to enforce the policy. Set to `false` to *turn off* the policy. The policy will not be enforced even if it remains attached to a flow. | true | Optional |
| `async` | This attribute is deprecated. | false | Deprecated |

## \<DisplayName\> element

Use in addition to the `name` attribute to label the policy in the
management UI proxy editor with a different, natural-language name.

```
<DisplayName>Policy Display Name</DisplayName>
```

| Default | N/A If you omit this element, the value of the policy's `name` attribute is used. |
| Presence | Optional |
| Type | String |
|---|---|

## \<EntityIdentifier\> element

Specifies the particular entity -- of the type given in EntityType -- to get.

```
<EntityIdentifier ref="value_variable" type="identifier_type"/> 
```

|---|---|
| **Default** | N/A |
| **Presence** | Required |
| **Type** | String |

### Attributes

| Attribute | Description | Default | Presence | Type |
|---|---|---|---|---|
| ref | The variable that provides the source of the identifier, such as `request.queryparam.apikey`. | N/A | Required. | String |
| type | The type populated by the variable in the ref attribute. such as `consumerkey`. See the [Entity types and identifiers](https://docs.apigee.com/api-platform/reference/policies/access-entity-policy#Entities) for a list of values. |   | Required. | String |

### Example

```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetCompany">
    <DisplayName>GetCompanyProfile</DisplayName>
    <EntityType value="company"></EntityType>
    <EntityIdentifier ref="request.queryparam.apikey" type="consumerkey"/>
</AccessEntity>
```

## \<EntityType\> element

Specifies the type of entity to retrieve from the data store.

```
<EntityType  value="entity_type"/>
```

|---|---|
| **Default** | N/A |
| **Presence** | Required |
| **Type** | String |

Use an [`EntityIdentifier`](https://docs.apigee.com/api-platform/reference/policies/access-entity-policy#EntityIdentifierElement) element to specify
which entity of the given type you want. For a reference of entity types, see the [Entity types and identifiers](https://docs.apigee.com/api-platform/reference/policies/access-entity-policy#Entities).

### Attributes

| Attribute | Description | Default | Presence | Type |
|---|---|---|---|---|
| value | One of the supported entity types. See [Entity types and identifiers](https://docs.apigee.com/api-platform/reference/policies/access-entity-policy#Entities) for a list. | None. | Required. | String |

## \<SecondaryIdentifier\> element

In conjunction with `EntityIdentifier`, specifies a value to identify the desired
instance of the given `EntityType`.

```
<SecondaryIdentifier ref="value_variable" type="identifier_type"/>
```

|---|---|
| **Default** | N/A |
| **Presence** | Optional |
| **Type** | String |

Use `SecondaryIdentifier` when specifying only an `EntityIdentifier`
will not guarantee that you get a single entity. See [Narrowing
results with secondary identifiers](https://docs.apigee.com/api-platform/reference/policies/access-entity-policy#secondary_identifiers) for more information.

Using multiple `SecondaryIdentifier` elements is not supported.

### Attributes

| Attribute | Description | Default | Presence | Type |
|---|---|---|---|---|
| ref | The variable that provides the source of the identifier, such as `request.queryparam.apikey`. | N/A | Required. | String |
| type | The type populated by the variable in the ref attribute. such as `consumerkey`. See the [Entity types and identifiers](https://docs.apigee.com/api-platform/reference/policies/access-entity-policy#Entities) for a list of values. |   | Required. | String |

### Example

```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetAPIProduct">
    <DisplayName>GetAPIProduct</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="developer.app.name" type="appname"/> 
    <SecondaryIdentifier ref="developer.id" type="developerid"/> 
</AccessEntity>
```

## Usage notes

### Narrowing results with secondary identifiers

For some entities, giving one identifier might not be specific enough to get the entity you
want. In those cases, you can use a secondary identifier to narrow the results.

> [!NOTE]
> **Note:** Where multiple matches exist for a given `EntityIdentifier` and `SecondaryIdentifier` combination, the first match will be populated in the flow. For example, consider a case in which you're wanting to get an API product profile by using an app ID.

Your first, possibly broad policy configuration might look like this:

```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetApp">
    <DisplayName>GetAppProfile</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="request.queryparam.apikey" type="consumerkey"/>
</AccessEntity>
```

Because an app can be associated with multiple API products, using just the app ID might not
return the API product you want (you could get just the first of multiple matched products).

Instead, to get a more exact result, you could use a `SecondaryIdentifier`. For
example, you might have `appname` and `developerid` variables in the flow
because these are populated by default during an OAuth 2.0 exchange. You could use the values of
those variables in an `AccessEntity` policy to get profile details on the requesting
app.

Your more specific policy configuration might look like this:

```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetApp">
    <DisplayName>GetAppProfile</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="developer.app.name" type="appname"/> 
    <SecondaryIdentifier ref="developer.id" type="developerid"/> 
</AccessEntity>
```

### Supported entity types and identifiers

`AccessEntity` supports the following entity types and identifiers.

| EntityType Value | EntityIdentifier Types | SecondaryIdentifier Types |
|---|---|---|
| `apiproduct` | `appid` | `apiresource` |
| `apiproduct` | `apiproductname` |   |
| `apiproduct` | `appname` | `apiresource` `developeremail` `developerid` `companyname` |
| `apiproduct` | `consumerkey` | `apiresource` |
| `app` | `appid` |   |
| `app` | `appname` | `developeremail` `developerid` `companyname` |
| `app` | `consumerkey` |   |
| `authorizationcode` | `authorizationcode` |   |
| `company` | `appid` |   |
| `company` | `company` |   |
| `company` | `consumerkey` |   |
| `companydeveloper` | `companyname` |   |
| `consumerkey` | `consumerkey` |   |
| `consumerkey_scope` | `consumerkey` |   |
| `developer` | `appid` |   |
| `developer` | `consumerkey` |   |
| `developer` | `developeremail` |   |
| `developer` | `developerid` |   |
| `requesttoken` | `requesttoken` | `consumerkey` |
| `verifier` | `verifier` |   |

### Example entity profile XML

To retrieve the entity profile value you want with XPath, you'll need to know something about
the profile XML's structure. For an example of the structure, use a management API call to get
XML for the entity you want. For details, refer to the [management API
reference](https://docs.apigee.com/management/apis).

The following sections include code for API calls, along with example XML from the call.

#### Apps

```
$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u email:password
```

See also [Get App in an
Organization by App ID](https://docs.apigee.com/management/apis/get/organizations/{org_name}/apps/{app_id}) in the Edge management API reference.

Or:

```
$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email}/apps/{app_name} \
-u email:password
```

See also [Get
Developer App Details](https://docs.apigee.com/management/apis/get/organizations/{org_name}/developers/{developer_email}/apps/{app_name}) in the Edge management API reference.

Sample profile:

```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<App name="thomas-app">
    <AccessType>read</AccessType>
    <ApiProducts/>
    <Credentials>
        <Credential>
            <Attributes/>
            <ConsumerKey>wrqOOOiPArFI0WRoB1gAJMRbOguekJ5w</ConsumerKey>
            <ConsumerSecret>WvOhDrJ8m6kzz7Ni</ConsumerSecret>
            <ApiProducts>
                <ApiProduct>
                    <Name>FreeProduct</Name>
                    <Status>approved</Status>
                </ApiProduct>
            </ApiProducts>
            <Scopes/>
            <Status>approved</Status>
        </Credential>
    </Credentials>
    <AppFamily>default</AppFamily>
    <AppId>ab308c13-bc99-4c50-8434-0e0ed1b86075</AppId>
    <Attributes>
        <Attribute>
            <Name>DisplayName</Name>
            <Value>Tom's Weather App</Value>
        </Attribute>
    </Attributes>
    <CallbackUrl>http://tom.app/login</CallbackUrl>
    <CreatedAt>1362502872727</CreatedAt>
    <CreatedBy>admin@apigee.com</CreatedBy>
    <DeveloperId>PFK8IwOeAOW01JKA</DeveloperId>
    <LastModifiedAt>1362502872727</LastModifiedAt>
    <LastModifiedBy>admin@apigee.com</LastModifiedBy>
    <Scopes/>
    <Status>approved</Status>
</App>
```

#### API product

```
$ curl  -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts/{apiproduct_name} \
-u email:password
```

See also [Get API
Product](https://docs.apigee.com/management/apis/get/organizations/{org_name}/apiproducts/{apiproduct_name}-0) in the Edge management API reference.

Sample XPath, retrieves the second API resource (URI) from the API product named
`weather_free`:

```
/ApiProduct['@name=weather_free']/ApiResources/ApiResource[1]/text()
```

Sample profile returned as XML:

```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApiProduct name="weather_free">
    <ApiResources>
        <ApiResource>/forecastrss, /reports</ApiResource>
    </ApiResources>
    <ApprovalType>auto</ApprovalType>
    <Attributes>
        <Attribute>
            <Name>description</Name>
            <Value>Introductory API Product</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.interval</Name>
            <Value>1</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.limit</Name>
            <Value>1</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.timeunit</Name>
            <Value>minute</Value>
        </Attribute>
        <Attribute>
            <Name>servicePlan</Name>
            <Value>Introductory</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1355847839224</CreatedAt>
    <CreatedBy>andrew@apigee.com</CreatedBy>
    <Description>Free API Product</Description>
    <DisplayName>Free API Product</DisplayName>
    <Environments/>
    <LastModifiedAt>1355847839224</LastModifiedAt>
    <LastModifiedBy>andrew@apigee.com</LastModifiedBy>
    <Proxies/>
    <Scopes/>
</ApiProduct>
```

#### Company

```
$ curl   -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name} \
-u email:password
```

See also [Get
Company Details](https://docs.apigee.com/management/apis/get/organizations/{org_name}/companies/{company_name}) in the Edge management API reference.

Sample profile:

```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Company name="theramin">
    <Apps/>
    <DisplayName>Theramin Corporation</DisplayName>
    <Organization>apigee-pm</Organization>
    <Status>active</Status>
    <Attributes>
        <Attribute>
            <Name>billing_code</Name>
            <Value>13648765</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1349208631291</CreatedAt>
    <CreatedBy>andrew@apigee.com</CreatedBy>
    <LastModifiedAt>1349208631291</LastModifiedAt>
    <LastModifiedBy>andrew@apigee.com</LastModifiedBy>
</Company>
```

#### Company developer

```
$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name}/developers/{developer_name} \
-u email:password
```

Sample profile:

```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developers>
    <Developer>
        <Email>ntesla@theramin.com</Email>
        <Role>developer</Role>
    </Developer>
</Developers>
```

#### Consumer key

```
$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email}/apps/{app_name}/keys/{consumer_key} \
-u email:password
```

See also [Get Key Details for a Developer App](https://docs.apigee.com/management/apis/get/organizations/{org_name}/developers/{developer_email}/apps/{app_name}/keys/{consumer_key}-0) in the Edge management API reference.

Sample XPath:

```
/Credential/ApiProducts/ApiProduct[Name='weather_free']/Status/text()
```

Sample profile:

```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Credential>
    <Attributes/>
    <ConsumerKey>XLotL3PRxNkUGXhGAFDPOr6fqtvAhuZe</ConsumerKey>
    <ConsumerSecret>iNUyEaOOh96KR3YL</ConsumerSecret>
    <ApiProducts>
        <ApiProduct>
            <Name>weather_free</Name>
            <Status>approved</Status>
        </ApiProduct>
    </ApiProducts>
    <Scopes/>
    <Status>approved</Status>
</Credential>
```

#### Developer

```
$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email} \
-u email:password
```

See also [Get Developer](https://docs.apigee.com/management/apis/get/organizations/{org_name}/developers/{developer_email}) in
the Edge management API reference.

Sample XPath:

```
/Developer/Attributes/Attribute[Name='my_custom_attribute']/Value/text()
```

```
/Developer/Email/text()
```

Sample profile:

```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developer>
    <Apps>
        <App>weatherappx</App>
        <App>weatherapp</App>
    </Apps>
    <Email>ntesla@theramin.com</Email>
    <DeveloperId>4Y4xd0KRZ1wmHJqu</DeveloperId>
    <FirstName>Nikola</FirstName>
    <LastName>Tesla</LastName>
    <UserName>theramin</UserName>
    <OrganizationName>apigee-pm</OrganizationName>
    <Status>active</Status>
    <Attributes>
        <Attribute>
            <Name>project_type</Name>
            <Value>public</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1349797040634</CreatedAt>
    <CreatedBy>rsaha@apigee.com</CreatedBy>
    <LastModifiedAt>1349797040634</LastModifiedAt>
    <LastModifiedBy>rsaha@apigee.com</LastModifiedBy>
</Developer>
```

*** ** * ** ***

## Flow variables

When the entity profile specified in the AccessEntity policy is retrieved, the XML-formatted
profile object is added to the message context as a variable. It can be accessed like any other
variable, with reference to the variable name. The user-provided name of the AccessEntity policy
is set as the variable prefix of the variable name.

For example, if an AccessEntity policy with name of `GetDeveloper` is executed,
then the XML-formatted profile is stored in the variable named
`AccessEntity.GetDeveloper`. The XML-formatted profile can then be parsed using an
XPath defined in an ExtractVariables policy that specifies `AccessEntity.GetDeveloper`
as its source.

## Error reference


For related information, see [What you need to know
about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors) and [Handling
faults](https://docs.apigee.com/api-platform/fundamentals/fault-handling).

### Runtime errors

None.

### Deployment errors

| Error name | Fault string | HTTP status | Occurs when |
|---|---|---|---|
| `InvalidEntityType` | `Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name]` | N/A | The entity type used must be one of the [supported types](https://docs.apigee.com/api-platform/reference/policies/access-entity-policy#Entities). |

<br />

## Related topics

> [!NOTE]
> **Sample:** For working samples of API proxies, see the [Samples list](https://docs.apigee.com/api-platform/samples/samples-reference).

- `ExtractVariables`: [ExtractVariables policy](https://docs.apigee.com/api-platform/reference/policies/extract-variables-policy)
- `AssignMessage`: [AssignMessage policy](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy)