export const metadata = {
title: 'Claims',
description:
'Learn about the seven standard PASETO claims and how to use them in your tokens.',
}
# Claims
PASETO defines seven standard claims for common token use cases. rusty_paseto provides type-safe wrappers for each. {{ className: 'lead' }}
## Standard Claims Overview
| Claim | Key | Description |
|-------|-----|-------------|
| Issuer | `iss` | Who created the token |
| Subject | `sub` | Who/what the token is about |
| Audience | `aud` | Who the token is intended for |
| Expiration | `exp` | When the token expires |
| Not Before | `nbf` | When the token becomes valid |
| Issued At | `iat` | When the token was created |
| Token ID | `jti` | Unique identifier for the token |
---
## Issuer Claim (iss)
Identifies who created and signed the token.
```rust
use rusty_paseto::prelude::*;
// Building
let token = PasetoBuilder::<V4, Local>::default()
.set_claim(IssuerClaim::from("auth.example.com"))
// or using fluent method
.issuer("auth.example.com")
.build(&key)?;
// Parsing - check issuer matches
let payload = PasetoParser::<V4, Local>::default()
.check_claim(IssuerClaim::from("auth.example.com"))
.parse(&token, &key)?;
```
---
## Subject Claim (sub)
Identifies the principal (user, service) the token represents.
```rust
use rusty_paseto::prelude::*;
// Building
let token = PasetoBuilder::<V4, Local>::default()
.set_claim(SubjectClaim::from("user_12345"))
// or using fluent method
.subject("user_12345")
.build(&key)?;
// Parsing - check subject matches
let payload = PasetoParser::<V4, Local>::default()
.check_claim(SubjectClaim::from("user_12345"))
.parse(&token, &key)?;
```
---
## Audience Claim (aud)
Identifies the intended recipient(s) of the token.
```rust
use rusty_paseto::prelude::*;
// Building
let token = PasetoBuilder::<V4, Local>::default()
.set_claim(AudienceClaim::from("api.example.com"))
// or using fluent method
.audience("api.example.com")
.build(&key)?;
// Parsing - reject tokens not intended for us
let payload = PasetoParser::<V4, Local>::default()
.check_claim(AudienceClaim::from("api.example.com"))
.parse(&token, &key)?;
```
---
## Expiration Claim (exp)
Specifies when the token expires. Must be an RFC3339 timestamp.
```rust
use rusty_paseto::prelude::*;
// Building with explicit timestamp
let token = PasetoBuilder::<V4, Local>::default()
.set_claim(ExpirationClaim::try_from("2025-01-01T00:00:00Z")?)
// or using fluent method
.expiration("2025-01-01T00:00:00Z")?
.build(&key)?;
// Building with duration
use time::{Duration, OffsetDateTime};
let exp = OffsetDateTime::now_utc() + Duration::hours(24);
let exp_str = exp.format(&time::format_description::well_known::Rfc3339)?;
let token = PasetoBuilder::<V4, Local>::default()
.set_claim(ExpirationClaim::try_from(exp_str.as_str())?)
.build(&key)?;
```
<Note>
`PasetoParser` automatically validates expiration. Expired tokens return
`Error::Expired`.
</Note>
---
## Not Before Claim (nbf)
Specifies when the token becomes valid. Useful for pre-issued tokens.
```rust
use rusty_paseto::prelude::*;
// Token valid starting tomorrow
let token = PasetoBuilder::<V4, Local>::default()
.set_claim(NotBeforeClaim::try_from("2024-12-25T00:00:00Z")?)
// or using fluent method
.not_before("2024-12-25T00:00:00Z")?
.build(&key)?;
```
<Note>
`PasetoParser` automatically validates not-before. Early tokens return
`Error::NotYetValid`.
</Note>
---
## Issued At Claim (iat)
Records when the token was created.
```rust
use rusty_paseto::prelude::*;
use time::OffsetDateTime;
let now = OffsetDateTime::now_utc()
.format(&time::format_description::well_known::Rfc3339)?;
let token = PasetoBuilder::<V4, Local>::default()
.set_claim(IssuedAtClaim::try_from(now.as_str())?)
// or using fluent method
.issued_at(now.as_str())?
.build(&key)?;
```
---
## Token ID Claim (jti)
A unique identifier for the token. Useful for revocation lists.
```rust
use rusty_paseto::prelude::*;
use uuid::Uuid;
let token_id = Uuid::new_v4().to_string();
let token = PasetoBuilder::<V4, Local>::default()
.set_claim(TokenIdentifierClaim::from(token_id.as_str()))
// or using fluent method
.token_identifier(&token_id)
.build(&key)?;
```
---
## Combining Claims
A typical authentication token uses multiple claims:
```rust
use rusty_paseto::prelude::*;
let token = PasetoBuilder::<V4, Local>::default()
.issuer("auth.myapp.com")
.subject("user_12345")
.audience("api.myapp.com")
.expiration("2025-01-01T00:00:00Z")?
.issued_at("2024-06-15T10:30:00Z")?
.token_identifier("tok_abc123")
.build(&key)?;
```