# SAIFSECURITY001: Security Configuration API is Experimental

## Cause

You are using a type or member from the SAIF security configuration API that is marked as experimental.

## Rule Description

The security configuration APIs in `SAIF.Platform.Aspire.Hosting.Security` are currently in preview and may change in future releases. These APIs allow you to:

- Define app roles and scopes for your API
- Configure business role to app role mappings for corporate (Entra) and external (Okta) users
- Declare upstream API dependencies with required permissions

## How to Fix

If you want to use these experimental APIs, suppress the warning:

### Option 1: Suppress in code

```csharp
#pragma warning disable SAIFSECURITY001
builder.AddSecurity()
    .WithCorporateAssignment(AppRoleAssignments.Admin);
#pragma warning restore SAIFSECURITY001
```

### Option 2: Suppress in project file

```xml
<PropertyGroup>
  <NoWarn>$(NoWarn);SAIFSECURITY001</NoWarn>
</PropertyGroup>
```

### Option 3: Suppress with attribute

```csharp
[assembly: System.Diagnostics.CodeAnalysis.SuppressMessage(
    "Usage",
    "SAIFSECURITY001:Type is for evaluation purposes only")]
```

## Affected APIs

| Type                            | Description                                        |
| ------------------------------- | -------------------------------------------------- |
| `SecurityResource`              | Security configuration resource for auth artifacts |
| `SecurityResourceExtensions`    | Extension methods for `AddSecurity()`              |
| `UpstreamApiResource`           | Upstream API dependency resource                   |
| `UpstreamApiResourceExtensions` | Extension methods for `AddUpstreamApi()`           |
| `AppRole`                       | Application role definition                        |
| `Scope`                         | OAuth2 scope definition                            |
| `BusinessRole`                  | Business role reference                            |
| `AppRoleAssignment`             | Business role to app role mapping                  |
| `SaifSecurityPublishingContext` | Publishing context for security artifacts          |

## When Will This Be Stable?

These APIs are being introduced as experimental in Forge 3.1. We are gathering feedback on:

- API ergonomics and naming conventions
- Generated configuration file formats
- Integration with Terraform modules

Once we have sufficient feedback and the API design has stabilized, we will remove the experimental designation in a future release.

Please provide feedback via the [Forge repository](https://github.com/saif-corp/forge/issues).