# Invoking Amazon ParallelCluster API
<a name="api-reference-invoke-v3"></a>

The Amazon ParallelCluster Amazon API Gateway endpoint is configured with [`AWS_IAM` authorization type](https://docs.amazonaws.cn/apigateway/latest/developerguide/permissions.html#api-gateway-control-access-iam-permissions-model-for-calling-api), and requires all requests to be SigV4 signed with valid IAM credentials ([API reference: making http requests](https://docs.amazonaws.cn/apigateway/api-reference/making-http-requests/)). 

When deployed with default settings, API invoke permissions are only granted to the default IAM user created with the API. 

To retrieve the ARN of the default IAM user, run: 

```
$ REGION={{<region>}}
$ API_STACK_NAME={{<stack-name>}}
$ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterApiUserRole'].OutputValue" --output text
```

To obtain temporary credentials for the default IAM user, run the [ STS AssumeRole](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sts/assume-role.html) command.

To retrieve the Amazon ParallelCluster API endpoint run the following command: 

```
$ REGION={{<region>}}
$ API_STACK_NAME={{<stack-name>}}
$ aws cloudformation describe-stacks --region ${REGION} --stack-name ${API_STACK_NAME} --query "Stacks[0].Outputs[?OutputKey=='ParallelClusterApiInvokeUrl'].OutputValue" --output text
```

The Amazon ParallelCluster API can be invoked by any HTTP client that complies with the OpenAPI specifications that can be found here: 

```
https://{{<REGION>}}-aws-parallelcluster.s3.{{<REGION>}}.amazonaws.com/parallelcluster/{{<VERSION>}}/api/ParallelCluster.openapi.yaml
```

Requests need to be SigV4 signed as documented [here](https://docs.amazonaws.cn/apigateway/api-reference/signing-requests). 

At this time, we do not offer any official API client implementation. However, you can use the [OpenAPI Generator](https://openapi-generator.tech/) to easily generate API clients from the OpenAPI model. Once the client is generated, SigV4 signing needs to be added if not provided out of the box. 

A reference implementation for a Python API client can be found in the [Amazon ParallelCluster repository](https://github.com/aws/aws-parallelcluster/tree/develop/api/client/src). To learn more about how you can use the Python API client, see the [Using the Amazon ParallelCluster API](tutorials_06_API_use.md) tutorial.

To implement more advanced access control mechanisms, such as Amazon Cognito or Lambda Authorizers, or to further protect the API with Amazon WAF or API keys, follow the [Amazon API Gateway documentation](https://docs.amazonaws.cn/apigateway/latest/developerguide/apigateway-control-access-to-api.html). 

**Warning**  
An IAM user that is authorized to invoke the Amazon ParallelCluster API, can indirectly control all Amazon resources managed by Amazon ParallelCluster in the Amazon Web Services account. This includes the creation of Amazon resources that the user can't control directly due to restrictions on the user IAM policy. For example, the creation of a Amazon ParallelCluster cluster, depending on its configuration, might include the deployment of Amazon EC2 instances, Amazon Route 53, Amazon Elastic File System file systems, Amazon FSx file systems, IAM roles, and resources from other Amazon Web Services services used by Amazon ParallelCluster that the user might not have direct control over.

**Warning**  
When you create a cluster with `AdditionalIamPolicies` specified in the configuration, the additional policies must match one of the following patterns:  

```
- !Sub arn:${AWS::Partition}:iam::${AWS::AccountId}:policy/parallelcluster*
- !Sub arn:${AWS::Partition}:iam::${AWS::AccountId}:policy/parallelcluster/*
- !Sub arn:${AWS::Partition}:iam::aws:policy/CloudWatchAgentServerPolicy
- !Sub arn:${AWS::Partition}:iam::aws:policy/AmazonSSMManagedInstanceCore
- !Sub arn:${AWS::Partition}:iam::aws:policy/AWSBatchFullAccess
- !Sub arn:${AWS::Partition}:iam::aws:policy/AmazonS3ReadOnlyAccess
- !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AWSBatchServiceRole
- !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AmazonEC2ContainerServiceforEC2Role
- !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
- !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AmazonEC2SpotFleetTaggingRole
- !Sub arn:${AWS::Partition}:iam::aws:policy/EC2InstanceProfileForImageBuilder
- !Sub arn:${AWS::Partition}:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
```
If you need other additional policies, you can do one of the following:  
Edit the `DefaultParallelClusterIamAdminPolicy` in:  

  ```
  https://{{<REGION>}}-aws-parallelcluster.s3.{{<REGION>}}.amazonaws.com/parallelcluster/{{<VERSION>}}/api/parallelcluster-api.yaml
  ```
Add the policy in the `ArnLike/iam:PolicyARN` section.
Don't specify policies for `AdditionalIamPolicies` in the configuration file and manually add policies to the Amazon ParallelCluster Instance Role created within the cluster.